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A  man  page  is  provided  for  both  the  naive  user,  and  sophisticated  user  who  is 
familiar  with  the  SunOS  operating  system  and  is  in  need  of  on-line  information. 

A  man  page  is  intended  to  answer  concisely  the  question  “What  does  it  do?’’  The 
man  pages  in  general  comprise  a  reference  manual.  They  are  not  intended  to  be  a 
tutorial. 

Below  is  a  generic  fonnat  for  man  pages.  The  man  pages  of  each  manual  section 
generally  follow  this  order,  but  include  only  needed  headings.  For  example,  if 
there  are  no  bugs  to  report,  there  is  no  BUGS  section.  If  a  man  page  documents 
System  V  behavior  in  addition  to  default  SunOS  behavior,  the  System  V  infor¬ 
mation  is  presented  under  SYSTEM  V  headings.  See  the  intro  pages  for  more 
information  about  each  section,  and  man(7)  for  more  information  about  man 
pages  in  general. 

This  section  gives  the  names  of  the  commands  or  functions  documented,  fol¬ 
lowed  by  a  brief  description  of  what  they  do. 

This  section  is  exclusive  to  Section  4.  It  lists  the  configuration  file  lines  needed 
to  install  a  driver  into  the  kernel.  Where  necessary,  the  configuration  lines  are 
presented  separately  for  different  hardware  platforms. 


This  section  shows  the  syntax  of  commands  or  functions.  When  a  command  or 
file  does  not  exist  in  the  standard  path,  its  fuU  pathname  is  shown.  Literal  char¬ 
acters  (commands  and  options)  are  in  bold  font  and  variables  (arguments,  param¬ 
eters  and  substitution  characters)  are  in  italic  font  Options  apd  ^tpffients  are 
alphabetized,  with  single  letter  arguments  first,  and  options  ;W®a^rrtfeiiits  next, 
unless  a  different  argument  order  is  required. 

The  following  special  characters  are  used  in  this 

[  ]  The  option  or  argument  enclosed  in  these  ifac|^S;ll^^ 
brackets  are  omitted,  the  argument  must  be  Sp|e|i|d. 
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AVAILABILITY 

DESCRIPTION 

lOCTLS 

OPTIONS 

RETURN  VALUES 

ERRORS 


Ellipses.  Several  values  may  be  provided  for  the  previous  argument,  or 
the  previous  argument  can  be  specified  multiple  times,  for  example, 

*  filename 

I  Separator.  Only  one  of  the  arguments  separated  by  this  character  can 
be  specified  at  time. 

This  section  occurs  only  in  subsection  3R  to  indicate  the  protocol  description  file. 
The  protocol  specification  pathname  is  always  listed  in  bold  font. 

This  section  briefly  states  any  limitations  on  the  availabilty  of  the  command. 
These  limitations  could  be  hardware  or  software  specific.  Software  specific  ones 
require  certain  installation  options. 

This  section  defines  the  functionality  and  behavior  of  the  service.  Thus  it 
describes  concisely  what  the  command  does.  It  does  not  discuss  OPTIONS  or  cite 
EXAMPLES.  Interactive  commands,  subcommands,  requests,  macros,  functions 
and  such,  are  described  under  USAGE. 

This  section  appears  on  pages  in  Section  4  only.  Only  the  device  class  which 
supplies  appropriate  parameters  to  the  ioctls(2)  system  call  is  called  ioctls  and 
generates  its  own  heading.  IOCTLS  for  a  specific  device  are  listed  alphabetically 
(on  the  man  page  for  that  specific  device).  IOCTLS  are  used  for  a  particular  class 
of  devices  all  which  have  an  io  ending,  such  as  nitio(4). 

This  lists  the  command  options  with  a  concise  summary  of  what  each  option 
does.  The  options  are  listed  literally  and  in  the  order  they  appear  in  the 
SYNOPSIS  section.  Possible  arguments  to  options  are  discussed  under  the 
option,  and  where  appropriate,  default  values  are  supplied. 

If  the  man  page  documents  functions  that  return  values,  this  section  lists  these 
values  and  describes  the  conditions  under  which  they  are  returned.  If  a  function 
can  return  only  constant  values,  such  as  0  or-l,  these  values  are  listed  in  tagged 
paragraphs.  Otherwise,  a  single  paragraph  describes  the  return  values  of  each 
function.  Functions  declared  as  void  do  not  return  values,  so  they  are  not  dis¬ 
cussed  in  RETURN  VALUES. 

On  failure,  most  functions  place  an  error  code  in  the  global  variable  errno  indi¬ 
cating  why  they  failed.  This  section  lists  alphabetically  all  error  codes  a  function 
can  generate  and  describes  the  conditions  that  cause  each  error.  When  more  than 
one  condition  can  cause  the  same  error,  each  condition  is  described  in  a  separate 
paragraph  under  the  error  code. 
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EXAMPLES 


ENVIRONMENT 

FILES 

SEE  ALSO 

DIAGNOSTICS 

WARNINGS 

NOTES 


This  section  is  provided  as  a  guidance  on  use.  This  section  lists  special  rules, 
features  and  commands  that  require  in-depth  explanations.  The  subsections 
listed  below  are  used  to  explain  built-in  functionality; 

Commands 
Modifiers 
Variables 
Expressions 
Input  Grammar 

This  section  provides  examples  of  usage  or  of  how  to  use  a  command  or  func¬ 
tion.  Wherever  possible  a  complete  example  including  command  line  entry  and 
machine  response  is  shown.  Whenever  an  example  is  given,  the  prompt  is  shown 
as 


example  % 

or  if  the  user  must  be  super-user, 
example# 

Examples  are  followed  by  explanations,  variable  substitution  mles,  or  returned 
values.  Most  examples  illustrate  concepts  from  the  SYNOPSIS,  DESCRIPTION, 
OPTIONS  and  USAGE  sections. 

This  section  lists  any  environment  variables  that  the  command  or  function 
affects,  followed  by  a  brief  description  of  the  effect. 

This  section  lists  all  filenames  referred  to  by  the  man  page,  files  of  interest,  and 
files  created  or  required  by  commands.  Each  is  followed  by  a  descriptive  sum¬ 
mary  or  explanation. 

This  section  lists  references  to  other  man  pages,  in-house  documentation  and  out¬ 
side  publications. 

This  section  lists  diagnostic  messages  with  a  brief  explanation  of  the  condition 
causing  the  error.  Messages  appear  in  bold  font  with  the  exception  of  variables, 
which  are  in  italic  font. 

This  section  lists  warnings  about  special  conditions  which  could  seriously  affect 
your  working  conditions  —  this  is  not  a  list  of  diagnostics. 

This  section  lists  additional  information  that  does  not  belong  anywhere  else  on 
the  page.  It  takes  the  form  of  an  aside  to  the  user,  covering  points  of  special 
interest.  Critical  information  is  never  covered  here. 


BUGS 


This  section  describes  known  bugs  and  wherever  possible  suggests  workarounds. 


I 


INTRO(l) 


USER  COMMANDS 


INTRO(l) 


NAME 

intro  -  introduction  to  commands 
DESCRIPTION 

This  section  describes  publicly  accessible  commands  in  alphabetic  order.  Commands  of  general  utility, 
many  with  enhancements  from  4.3  BSD. 

Pages  of  special  interest  have  been  categorized  as  follows: 

1C  Commands  for  communicating  with  other  systems. 

IG  Commands  used  primarily  for  graphics  and  computer-aided  design. 

IV  System  V  commands.  One  or  more  of  the  following  are  true: 

•  The  man  page  documents  System  V  behavior  only, 

•  The  man  page  documents  default  SunOS  behavior,  and  System  V  behavior  as  it  differs 
from  the  default  behavior.  These  System  V  differences  are  presented  under  SYSTEM  V 
section  headers. 

•  The  man  page  documents  behavior  compliant  with  IEEE  Std  1003J~1988  (POSIX.l). 

SEE  ALSO 

•  Section  8  in  this  manual  for  system  administration  procedures,  system  maintenance  and  operation  com¬ 
mands,  local  daemons,  and  network-services  servers. 

•  Section  7  in  this  manual  for  descriptions  of  publicly  available  files  and  macro  packages  for  document 
preparation. 

•  Section  6  in  this  manual  for  computer  games. 

•  SunOS  User’s  Guide:  Getting  Started 

•  SunOS  User’s  Guide:  Customizing  Your  Environment 

•  SunView  User’s  Guide 

•  SunOS  User's  Guide:  Doing  More 

•  Programming  Utilities  and  Libraries 
DIAGNOSTICS 

Upon  termination  each  command  returns  two  bytes  of  status,  one  supplied  by  the  system  giving  the  cause 
for  termination,  and  (in  the  case  of  “normal”  termination)  one  supplied  by  the  program,  see  wait(2V)  and 
exit(2V).  The  former  byte  is  0  for  normal  termination,  the  latter  is  customarily  0  for  successful  execution, 
nonzero  to  indicate  troubles  such  as  erroneous  parameters,  bad  or  inaccessible  data,  or  other  inability  to 
cope  with  the  task  at  hand.  It  is  called  variously  “exit  code,”  “exit  status”  or  “return  code,”  and  is 
described  only  where  special  conventions  are  involved. 
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INTRO(l) 


LIST  OF  COMMANDS 


Name 

Appears  on  Page 

acctcom 

acctcom  (1) 

adb 

adb(l) 

addbib 

addbib(l) 

adjacentscreens 

adjacentscreens(l) 

admin 

sccs-admin(l) 

aedplot 

plot(lG) 

alias 

csh(l) 

align^equals 

textedit_filters(l) 

apropos 

apropos(l) 

ar 

ar(lV) 

arch 

arch(l) 

as 

as(l) 

at 

at(l) 

atq 

atq(l) 

atrm 

atrm(l) 

awk 

awk(i) 

banner 

banner  (IV) 

bar 

bar(l) 

basename 

basename(lV) 

batch 

at(l) 

be 

bed) 

bg 

csh(l) 

bgplot 

plot(lG) 

biff 

biff(l) 

bin-mail 

bin-mail(l) 

break 

csh(l) 

breaksw 

csh(l) 

cal 

cal(l) 

calendar 

calendar(l) 

cancel 

Ip(l) 

capitalize 

textedit  filters(l) 

case 

csh(l) 

cat 

cat(lV) 

cb 

cb(l) 

cc 

cc(lV) 

cd 

cd(l) 

ede 

sccs-cdc(l) 

cflow 

cflow(lV) 

checkeq 

eqn(l) 

checknr 

checknr  (1) 

chfn 

passwd(l) 

chgrp 

chgrp(l) 

chkey 

chkey(l) 

chmod 

chmod(lV) 

chsh 

passwd(l) 

clear 

clear(l) 

clear_colormap 

clear_color  map  ( 1 ) 

clear_functions 

clear_functions(l) 

click 

click(l) 

clock 

clock(l) 

Description 

search  and  print  process  accounting  files 

general-purpose  debugger 

create  or  extend  a  bibliographic  database 

connect  multiple  screens  to  SunView  window  driver 

create  and  administer  SCCS  history  files 

graphics  filters  for  various  plotters 

C  shell  built-in  commands,  see  csh(l) 

filters  provided  with  textedit(l) 

locate  commands  by  keyword  lookup 

create  library  archives,  and  add  or  extract  files 

display  the  architecture  of  the  current  host 

assembler 

execute  a  command  or  script  at  a  specified  time 

display  the  queue  of  jobs  to  be  run  at  specified  times 

remove  jobs  spooled  by  at  or  batch 

pattern  scanning  and  processing  language 

display  a  string  in  large  letters 

create  tape  archives,  and  add  or  extract  files 

display  portions  of  pathnames  and  filenames 

execute  a  command  or  script  at  a  specified  time 

arbitrary-precision  arithmetic  language 

C  shell  built-in  commands,  see  csh(l) 

graphics  filters  for  various  plotters 

give  notice  of  incoming  mail  messages 

an  early  program  for  processing  mail  messages 

C  shell  built-in  commands,  see  csh(l) 

C  shell  built-in  commands,  see  csh(l) 
display  a  calendar 
a  simple  reminder  service 
send/cancel  requests  to  a  printer 
filters  provided  with  textedit(l) 

C  shell  built-in  commands,  see  csh(l) 
concatenate  and  display 
a  simple  C  program  beautifier 
C  compiler 

change  working  directory 
change  the  delta  commentary  of  an  SCCS  delta 
generate  a  flow  graph  for  a  C  program 
typeset  mathematics 

check  nroff  and  troff  input  files  for  errors 

change  local  or  NIS  password  information 

change  the  group  ownership  of  a  file 

create  or  change  encryption  key 

change  the  permissions  mode  of  a  file 

change  local  or  NIS  password  information 

clear  the  terminal  screen 

clear  the  colormap  to  make  console  text  visible 

reset  the  selection  service  to  clear  stuck  function  keys 

enable  or  disable  the  keyboard’s  keystroke  click 

display  the  time  in  an  icon  or  window 
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cluster 

cluster  (1) 

cmdtool 

cmdtool(l) 

cmp 

cmp(l) 

col 

col(lV) 

colcrt 

colcrt(l) 

coloredit 

coloredit(l) 

colrm 

colrm  (1) 

comb 

sccs-comb(l) 

comm 

comm(l) 

compress 

compress(l) 

continue 

csh(l) 

cp 

cp(l) 

cpio 

cpio(l) 

cpp 

cpp(l) 

crontab 

crontab(l) 

crtplot 

plot(lG) 

crypt 

crypt(l) 

csh 

csh(l) 

csplit 

csplit(lV) 

ctags 

ctags(l) 

ctrace 

ctrace(lV) 

cu 

cu(lC) 

cut 

cut(lV) 

cxref 

cxref(lV) 

date 

date(lV) 

dbx 

dbx(l) 

dbxtool 

dbxtool(l) 

dc 

dc(l) 

dd 

dd(l) 

default 

csh(l) 

defaultsedit 

defaultsedit(l) 

defaults_from_input 

defaultsedit(l) 

defaults_from_input 

mput_from_defaults(l) 

defaults_toJndentpro 

defaultsedit(l) 

defaultsJo_mailrc 

defaultsedit(l) 

delta 

sccs-delta(l) 

deroff 

deroff(l) 

des 

des(l) 

df 

df(lV) 

diff 

diff(l) 

difl3 

diff3(lV) 

diffmk 

diffmk(l) 

dircmp 

dircmp(lV) 

dirname 

basename(lV) 

dirs 

csh(l) 

dis 

dis(l) 

disablenumlock 

enablenumlock(l) 

domainname 

domamname(l) 

dos 

dos(l) 

dos2unix 

dos2unix(l) 

du 

du(lV) 

dumbplot 

plot(lG) 

dumpkeys 

loadkeys(l) 

find  optional  cluster  containing  a  file 

run  a  shell  (or  program)  using  the  SunView  text  facility 

perform  a  byte-by-byte  comparison  of  two  files 

filter  reverse  paper  motions  for  terminal  diplay 

filter  nroff  output  for  a  terminal  lacking  overstrike  capability 

alter  color  map  segment 

remove  characters  from  specified  columns  within  each  line 
combine  SCCS  deltas 

display  lines  in  common  between  two  sorted  lists 
compress  or  expand  files,  display  expanded  contents 
C  shell  built-in  commands,  see  csh(l) 
copy  files 

copy  file  archives  in  and  out 

the  C  language  preprocessor 

install,  edit,  remove  or  list  a  user’s  crontab  file 

graphics  filters  for  various  plotters 

encode  or  decode  a  file 

shell  with  a  C-like  syntax  and  advanced  interactive  features 

split  a  file  with  respect  to  a  given  context 

create  a  tags  file  for  use  with  ex  and  vi 

generate  a  C  program  execution  trace 

connect  to  remote  system 

remove  selected  fields  from  each  line  of  a  file 

generate  a  C  program  cross-reference 

display  or  set  the  date 

source-level  debugger 

SunView  interface  for  dbx  source-level  debugger 
desk  calculator 

convert  and  copy  files  with  various  data  formats 

C  shell  built-in  commands,  see  csh(l) 

edit  default  settings  for  SunView  utilities 

edit  default  settings  for  SunView  utilities 

update  current  slate  of  the  mouse  and  keyboard 

edit  default  settings  for  SunView  utilities 

edit  default  settings  for  SunView  utilities 

make  a  delta  to  an  SCCS  file 

remove  nroff,  troff,  tbl  and  eqn  constructs 

encrypt  or  decrypt  data  using  Data  Encryption  Standard 

report  free  disk  space  on  file  systems 

display  line-by-line  differences  between  pairs  of  text  files 

display  line-by-line  differences  between  3  files 

mark  differences  between  versions  of  a  troff  input  file 

compare  directories 

display  portions  of  pathnames  and  filenames 

C  shell  built-in  commands,  see  csh(l) 

object  code  disassembler  for  COFF 

enable  or  disable  the  numlock  key 

set  or  display  name  of  the  current  NIS  domain 

SunView  window  for  IBM  PC/AT  applications 

convert  text  file  from  DOS  format  to  ISO  format 

display  the  number  of  disk  blocks  used  per  directory  or  file 

graphics  filters  for  various  plotters 

load  and  dump  keyboard  translation  tables 
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e 

ex(l) 

line  editor 

echo 

echo(lV) 

echo  arguments  to  the  standard  output 

ed 

ed(l) 

basic  line  editor 

edit 

ex(l) 

line  editor 

egrep 

grep(lV) 

search  a  file  for  a  string  or  regular  expression 

eject 

eject(l) 

eject  media  device  from  drive 

elise 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

enablenumlock 

enablenumlock(l) 

enable  or  disable  the  numlock  key 

end 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

endif 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

endsw 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

enroll 

xsend(l) 

send  or  receive  secret  mail 

env 

env(l) 

obtain  or  alter  environment  variables 

eqn 

eqn(l) 

typeset  mathematics 

error 

error (1) 

categorize  compiler  error  messages,  insert  at  source  file  lines 

eval 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

ex 

ex(l) 

line  editor 

exec 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

exit 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

expand 

expand(l) 

expand  TAB  characters  to  SPACE  characters,  and  vice  versa 

expr 

expr(lV) 

evaluate  expressions  as  logical,  arithmetic,  or  string 

false 

true(l) 

provide  truth  values 

fdformat 

fdformat(l) 

format  diskettes 

fg 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

fgrep 

grep(lV) 

search  a  file  for  a  string  or  regular  expression 

file 

file(l) 

determine  the  type  of  a  file  by  examining  its  contents 

find 

find(l) 

find  files  by  name,  or  by  other  characteristics 

finger 

finger(l) 

display  information  about  users 

fmt 

ftnt(l) 

simple  text  and  mail-message  formatters 

fmt  mail 

fmt(l) 

simple  text  and  mail-message  formatters 

fold 

fold(l) 

fold  long  lines  for  display 

fontedit 

fontedit(l) 

a  vfont  screen-font  editor 

foption 

foption(l) 

determine  available  floating-point  code  generation  options 

foreach 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

from 

from(l) 

display  the  sender  and  date  of  newly-arrived  mail  messages 

ftp 

ftp(lC) 

file  transfer  program 

gcore 

gcore  (1) 

get  core  images  of  running  processes 

get 

sccs-get(l) 

retrieve  a  version  of  an  SCCS  file 

get_alarm 

set_alarm(l) 

SunView  programmable  alarms 

getoptcvt 

getopts(l) 

parse  command  options  in  shell  scripts 

getopt 

getopt(lV) 

parse  command  options  in  shell  scripts 

getopts 

getopts(l) 

parse  command  options  in  shell  scripts 

get_selection 

get_selection(l) 

copy  contents  of  SunView  selection  to  the  standard  output 

gfxtool 

gfxtool(l) 

run  graphics  programs  in  a  SunView  window 

gigiplot 

plot(lG) 

graphics  filters  for  various  plotters 

glob 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

goto 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

gprof 

gprof(l) 

display  call-graph  profile  data 

graph 

graph(lG) 

draw  a  graph 

grep 

grep(lV) 

search  a  file  for  a  string  or  regular  expression 

groups 

groups(l) 

display  a  user’s  group  memberships 

hashcheck 

spell(l) 

report  spelling  errors 

hashmake 

spell(l) 

report  spelling  errors 
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hashstat 

csh(l) 

head 

head(l) 

help 

sccs-help(l) 

help_viewer 

help_viewer(l) 

history 

csh(r) 

hostid 

hostid(l) 

hostname 

hostname(l) 

hpplot 

plot(lG) 

1386 

machid(l) 

iAPX286 

machid(l) 

iconedit 

iconedit(l) 

id 

id(lV) 

if 

csh(l) 

implot 

plot(lG) 

indent 

indent(l) 

indentprotodefaults 

defaultsedit(l) 

indxbib 

indxbib(l) 

inline 

inline(l) 

input_from_defaults 

defaultsedit(l) 

input_from_defaults 

input_from_defaults(l) 

insertbrackets 

textedit_filters(l) 

install 

install(l) 

ipcrm 

ipcrm(l) 

ipcs 

ipcs(l) 

jobs 

csh(l) 

join 

join(l) 

keylogin 

keylogin(l) 

keylogout 

keylogout(l) 

kill 

kill(l) 

label 

csh(l) 

last 

last(l) 

lastcomm 

lastcomm(l) 

Id 

Id(l) 

Idd 

Idd(l) 

ld.so 

ld(l) 

leave 

leave(l) 

lex 

lex(l) 

limit 

csh(l) 

line 

line(l) 

lint 

lint(lV) 

In 

In(lV) 

load 

load(l) 

loadc 

load(l) 

loadkeys 

loadkeys(l) 

lockscreendefault 

defaultsedit(l) 

lockscreen_default 

lockscreen(l) 

lockscreen 

lockscreen(l) 

logger 

logger(l) 

login 

login(l) 

It^name 

logname(l) 

l(^OUt 

csh(l) 

look 

look(l) 

lookbib 

lookbib(l) 

C  shell  built-in  commands,  see  csh(l) 
display  first  few  lines  of  specified  files 
help  regarding  SCCS  error  or  warning  messages 
provide  help  with  SunView  applications  and  desktop 
C  shell  built-in  commands,  see  csh(l) 
print  the  numeric  identifier  of  the  current  host 
set  or  print  name  of  current  host  system 
graphics  filters  for  various  plotters 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

create  and  edit  images  for  icons,  cursors  and  panel  items 

print  the  user  name  and  ID,  and  group  name  and  ID 

C  shell  built-in  commands,  see  csh(l) 

graphics  filters  for  various  plotters 

indent  and  format  a  C  program  source  file 

edit  default  settings  for  SunView  utilities 

create  an  inverted  index  to  a  bibliographic  database 

in-line  procedure  call  expander 

edit  default  settings  for  SunView  utilities 

update  the  current  state  of  the  mouse  and  keyboard 

filters  provided  with  textedit(l) 

install  files 

remove  a  message  queue,  semaphore  set,  or  shared  memory  ID 

report  interprocess  communication  facilities  status 

C  shell  built-in  commands,  see  csh(l) 

relational  database  operator 

decrypt  and  store  secret  key 

delete  stored  secret  key 

send  a  signal  to  a  process,  or  terminate  a  process 

C  shell  built-in  commands,  see  csh(l) 

indicate  last  logins  by  user  or  terminal 

show  the  last  commands  executed,  in  reverse  order 

link  editor,  dynamic  link  editor 

list  dynamic  dependencies 

link  editor,  dynamic  link  editor 

remind  you  when  you  have  to  leave 

lexical  analysis  program  generator 

C  shell  built-in  commands,  see  csh(l) 

read  one  line 

a  C  program  verifier 

make  hard  or  symbolic  links  to  files 

load  clusters 

load  clusters 

load  and  dump  keyboard  translation  tables 

edit  default  settings  for  SunView  utilities 

maintain  SunView  context  and  prevent  unauthorized  access 

maintain  SunView  context  and  prevent  unauthorized  access 

add  entries  to  the  system  log 

log  in  to  the  system 

get  the  name  by  which  you  logged  in 

C  shell  built-in  commands,  see  csh(l) 

find  words  in  the  system  dictionary  or  lines  in  a  sorted  list 

find  references  in  a  bibliographic  database 
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lorder 

Ip 

Ipq 

Ipr 

Ipriii 

Ipstat 

Iptest 

Is 

Isw 

in4 

m68k 

mach 

machid 

Mail 

mailrc_to_defaults 

mailtool 

make 

man 

mesg 

mkdir 

mkstr 

more 

mt 

rov 

nawk 

neqn 

newgrp 

nice 

nl 

nm 

nohup 

notify 

nroff 

objdump 

od 

old-ccat 

old-compact 

old-eyacc 

old-filemerge 

old-make 

old-prmail 

old-pti 

old-setkeys 

old-sun3cvt 

old-syslog 

old-uncompact 

old-vc 

on 

onintr 

organizer 

overview 

pack 

page 
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INTRO(l) 


lorder(l) 

find  an  ordering  relation  for  an  object  library 

lp(l) 

send/cancel  requests  to  a  printer 

Ipq(l) 

display  the  queue  of  printer  jobs 

Ipr(l) 

send  a  job  to  the  printer 

Iprm(l) 

remove  jobs  from  the  printer  queue 

Ipstat(l) 

display  the  printer  status  information 

Iptest(l) 

generate  lineprinter  ripple  pattern 

Is(lV) 

list  the  contents  of  a  directory 

Isw(l) 

list  TFS  whiteout  entries 

m4(lV) 

macro  language  processor 

macliid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

mach(l) 

display  the  processor  type  of  the  current  host 

machid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

mail(l) 

read  or  send  mail  messages 

defaultsedit(l) 

edit  default  settings  for  Sun  View  utilities 

mailtool(l) 

SunView  interface  for  the  mail  program 

make(l) 

maintain,  update,  and  regenerate  related  programs  and  files 

man(l) 

display  reference  manual  pages 

mesg(l) 

permit  or  deny  messages  on  the  terminal 

mkdir(l) 

make  a  directory 

mkstr(l) 

create  an  error  message  file  by  massaging  C  source  files 

more(l) 

browse  or  page  through  a  text  file 

mt(l) 

magnetic  tape  control 

mv(l) 

move  or  rename  files 

nawk(l) 

pattern  scanning  and  processing  language 

eqn(l) 

typeset  mathematics 

newgrp(l) 

log  in  to  a  new  group 

nice(l) 

run  a  command  at  low  priority 

nl(lV) 

line  numbering  filter 

nm(l) 

print  symbol  name  list 

nohup(lV) 

run  a  command  immune  to  hangups  and  quits 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

nroff(l) 

format  documents  for  display  or  line-printer 

objdump(l) 

dump  selected  parts  of  a  COFF  object  file 

od(lV) 

octal,  decimal,  hexadecimal,  and  ascii  dump 

old-compact(l) 

compress  and  uncompress  files,  and  cat  them 

old-compact(l) 

compress  and  uncompress  files,  and  cat  them 

old-eyacc(l) 

modified  yacc  allowing  much  improved  error  recovery 

old-filemerge(l) 

window-based  file  comparison  and  merging  program 

old-make(l) 

maintain,  update,  and  regenerate  groups  of  programs 

old-prmail(l) 

display  waiting  mail 

old-pti(l) 

phototypesetter  interpreter 

old-setkeys(l) 

modify  interpretation  of  the  keyboard 

old-sun3cvt(l) 

convert  Sun-2  system  executables  to  Sun-3  system  executables 

old-syslog(l) 

make  a  system  log  entry 

old-compact(l) 

compress  and  uncompress  files,  and  cat  them 

oid-vc(l) 

version  control 

on(lC) 

execute  command  on  a  remote  system  with  local  environment 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

organizer(l) 

file  and  directory  manager 

overview(l) 

run  a  program  from  SunView  that  takes  over  the  screen 

pack(lV) 

compress  and  expand  files 

more(l) 

browse  or  page  through  a  text  file 
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pagesize 

pagesize(l) 

display  the  size  of  a  page  of  memory 

passwd 

passwd(l) 

change  local  or  MIS  password  information 

paste 

paste(lV) 

join  corresponding  lines  of  files,  subsequent  lines  of  one 

pax 

pax(lV) 

portable  archive  exchange 

paxcpio 

paxepio(lV) 

copy  file  archives  in  and  out 

peat 

pack(lV) 

compress  and  expand  files 

pdpll 

maehid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

perfmeter 

perfineter(l) 

display  system  performance  values  in  a  meter  or  strip  chart 

Pg 

pg(lV) 

page  through  a  file  on  a  soft-copy  terminal 

plot 

plot(lG) 

graphics  filters  for  various  plotters 

popd 

esh(l) 

C  shell  built-in  commands,  see  csh(l) 

pr 

pr(lV) 

prepare  file(s)  for  printing,  perhaps  in  multiple  columns 

prmtenv 

printenv(l) 

display  environment  variables  currently  set 

prof 

prof(l) 

display  profile  data 

prs 

sees“prs(l) 

display  selected  portions  of  an  SCCS  history 

prt 

sees“prt(l) 

display  delta  table  information  from  an  SCCS  file 

ps 

ps(l) 

display  the  status  of  current  processes 

ptx 

ptx(l) 

generate  a  permuted  index 

pushd 

esh(l) 

C  shell  built-in  commands,  see  csh(l) 

pwd 

pwd(l) 

display  the  pathname  of  the  current  working  directory 

quota 

quota(l) 

display  a  user’s  disk  quota  and  usage 

ranlib 

ranlib(l) 

convert  archives  to  random  libraries 

rasfilterStol 

rasfilter8tol(l) 

convert  an  8-bit  deep  rasterfile  to  a  1-bit  deep  rasterfile 

rastrepl 

rastrepl(l) 

magnify  a  raster  image  by  a  factor  of  two 

rep 

rcp(lC) 

remote  file  copy 

rdist 

rdist(l) 

remote  file  distribution  program 

red 

ed(l) 

basic  line  editor 

refer 

refer (1) 

expand  and  insert  references  from  a  bibliographic  database 

rehash 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

remove^raekets 

textedit_fi[lters(l) 

filters  provided  with  textedit(l) 

repeat 

esh(l) 

C  shell  built-in  commands,  see  csh(l) 

reset 

tset(l) 

establish  or  restore  terminal  characteristics 

rev 

rev(l) 

reverse  the  order  of  characters  in  each  line 

ring_alarm 

set_alarm(l) 

SunView  programmable  alarms 

rlogin 

rlogin(lC) 

remote  login 

rm 

rin(l) 

remove  (unlink)  files  or  directories 

rmdel 

sees-rmdel(l) 

remove  a  delta  from  an  SCCS  file 

rmdir 

rm(l) 

remove  (unlink)  files  or  directories 

roffbib 

roffbib(l) 

format  and  print  a  bibliographic  database 

rpegen 

rpegen(l) 

RPC  protocol  compiler 

rsh 

rsh(lC) 

remote  shell 

rup 

rup(lC) 

show  host  status  of  local  machines  (RPC  version) 

ruptime 

ruptime(lC) 

show  host  status  of  local  machines 

rusers 

rusers(lC) 

who’s  logged  in  on  local  machines  (RPC  version) 

rwall 

rwall(lC) 

write  to  all  users  over  a  network 

rwho 

rwho(lC) 

who’s  logged  in  on  local  machines 

saet 

sees-saet(l) 

show  editing  activity  status  of  an  SCCS  file 

sees 

sees(l) 

front  end  for  the  Source  Code  Control  System  (SCCS) 

sees>admin 

sees-admin(l) 

create  and  administer  SCCS  history  files 

sees-ede 

sees“ede(l) 

change  the  delta  commentary  of  an  SCCS  delta 

sees-eomb 

sees-eomb  (1) 

combine  SCCS  deltas 

sees-delta 

sees-delta(l) 

make  a  delta  to  an  SCCS  file 

seesdiff 

sees-seesdiff(l) 

compare  two  versions  of  an  SCCS  file 
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sccs-get 

sccs-get(l) 

sccs-help 

sccs“help(l) 

sccs-prs 

sccs-prs(l) 

sccs-prt 

sccs-prt(l) 

sccs-rmdel 

sccs-rmdel(l) 

sccs-sact 

sccs-sact(l) 

sccs-scGsdiff 

sccs-sccsdifr(l) 

sccs-unget 

sccs-unget(l) 

sccs-val 

sccs-val(l) 

screenblank 

screenblank(l) 

screendump 

screendump(l) 

screenload 

screenload(l) 

script 

script(l) 

scrolldefaults 

defaultsedit(l) 

sdiff 

sdiff(lV) 

sed 

sed(lV) 

selection_svc 

selection_svc(l) 

set^alarm 

set  alarm(l) 

setenv 

csh(l) 

set 

csh(l) 

sh 

sh(l) 

shelltool 

shelltool(l) 

shift 

csh(l) 

shift_lines 

textedit_filters(l) 

size 

size(l) 

sleep 

sleep(l) 

snap 

snap(l) 

soelim 

soelim(l) 

sort 

sort(lV) 

sortbib 

sortbib(l) 

source 

csh(l) 

spare 

machid(l) 

spell 

spell(l) 

spellin 

spell(l) 

spline 

spline(lG) 

split 

split(l) 

stop 

csh(l) 

strings 

strings(l) 

strip 

strip(l) 

stty 

stty(lV) 

sttyfromdefaults 

defaultsedit(l) 

stty_froni_defaults 

stty  from  defaults(l) 

su 

su(iv) 

sum 

sum(lV) 

sun 

ma€hid(l) 

sun  view 

sunview(l) 

suspend 

csh(l) 

sv_acquire 

sv_acquire(l) 

sv_release 

sv_acquire(l) 

swin 

swin(l) 

switcher 

switcher  (1) 

switch 

csh(l) 

symorder 

symorder(l) 

retrieve  a  version  of  an  SCCS  file 

ask  for  help  regarding  SCCS  error  or  warning  messages 

display  selected  portions  of  an  SCCS  history 

display  delta  table  information  from  an  SCCS  file 

remove  a  delta  from  an  SCCS  file 

show  editing  activity  status  of  an  SCCS  file 

compare  two  versions  of  an  SCCS  file 

undo  a  previous  get  of  an  SCCS  file 

validate  an  SCCS  file 

turn  off  the  screen  when  the  mouse  and  keyboard  are  idle 

dump  a  frame-buffer  image  to  a  file 

load  a  frame-buffer  image  from  a  file 

make  typescript  of  a  terminal  session 

edit  default  settings  for  SunView  utilities 

contrast  two  text  files  by  displaying  them  side-by-side 

stream  editor 

SunView  selection  service 
SunView  programmable  alarms 
C  shell  built-in  commands,  see  csh(l) 

C  shell  built-in  commands,  see  csh(l) 

standard  UNIX  system  shell  and  command-level  language 

run  a  shell  in  a  SunView  terminal  window 

C  shell  built-in  commands,  see  csh(l) 

filters  provided  with  textedit(l) 

display  the  size  of  an  object  file 

suspend  execution  for  a  specified  interval 

SunView  application  for  system  and  network  administration 

resolve  and  eliminate  .so  requests  from  nroff  or  troff  input 

sort  and  collate  lines 

sort  a  bibliographic  database 

C  shell  built-in  commands,  see  csh(l) 

return  a  true  exit  status  if  the  processor  is  of  indicated  type 

report  spelling  errors 

report  spelling  errors 

interpolate  smooth  curve 

split  a  file  into  pieces 

C  shell  built-in  commands,  see  csh(l) 

find  printable  strings  in  an  object  file  or  binary 

remove  symbols  and  relocation  bits  from  an  object  file 

set  or  alter  the  options  for  a  terminal 

edit  default  settings  for  SunView  utilities 

set  terminal  editing  characters  from  the  defaults  database 

super-user,  temporarily  switch  to  a  new  user  ID 

calculate  a  checksum  for  a  file 

return  a  true  exit  status  if  the  processor  is  of  indicated  type 

the  SunView  window  environment 

C  shell  built-in  commands,  see  csh(l) 

change  owner,  group,  mode  of  window  devices 

change  owner,  group,  mode  of  window  devices 

set  or  get  SunView  user  input  options 

switch  between  multiple  desktops  on  the  same  physical  screen 

C  shell  built-in  commands,  see  csh(l) 

rearrange  a  list  of  symbols 
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sync 

sync(l) 

update  the  super  block;  force  changed  blocks  to  the  disk 

sysex 

sysex(l) 

start  the  system  exerciser 

syswait 

syswait(l) 

execute  a  command,  suspending  termination  until  user  input 

t300 

plot(lG) 

graphics  filters  for  various  plotters 

t300s 

pIot(lG) 

graphics  filters  for  various  plotters 

14013 

pIot(lG) 

graphics  filters  for  various  plotters 

1450 

plot(lG) 

graphics  filters  for  various  plotters 

labs 

tabs(lV) 

set  tab  stops  on  a  terminal 

lail 

tail(l) 

display  the  last  part  of  a  file 

lalk 

talk(l) 

talk  to  another  user 

lar 

tar(l) 

create  tape  archives,  and  add  or  extract  files 

Ibl 

tbi(l) 

format  tables  for  nroff  or  troff 

Icopy 

tcopy(l) 

copy  a  magnetic  tape 

Icov 

tcov(l) 

construct  test  coverage  analysis 

lee 

tee(l) 

replicate  the  standard  output 

lek 

pIot(lG) 

graphics  filters  for  various  plotters 

leklool 

tektool(l) 

SunView  Tektronix  4014  terminal-emulator  window 

lelnel 

telnet(lC) 

user  interface  to  a  remote  system  using  the  TELNET  protocol 

lesl 

test(lV) 

return  true  or  false  according  to  a  conditional  expression 

lexledil 

textedit(l) 

SunView  window-  and  mouse-based  text  editor 

lexledil  fillers 

textedit  filters(l) 

filters  provided  with  textedit(l) 

Iftp 

tftp(lC) 

trivial  file  transfer  program 

Ihen 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

lime 

time(lV) 

time  a  command 

lip 

tip(lC) 

connect  to  remote  system 

loolplaces 

too]places(l) 

display  current  window  locations,  sizes,  and  other  attributes 

touch 

touch(lV) 

update  the  access  and  modification  times  of  a  file 

tput 

tput(lV) 

initialize  a  terminal  or  query  the  terminfo  database 

tr 

tr(lV) 

translate  characters 

trace 

trace(l) 

trace  system  calls  and  signals 

traffic 

traffic(lC) 

SunView  program  to  display  Ethernet  traffic 

troff 

troff(l) 

typeset  or  format  documents 

true 

true(l) 

provide  truth  values 

tset 

tset(l) 

establish  or  restore  terminal  characteristics 

tsort 

tsort(l) 

topological  sort 

tty 

tty(i) 

display  the  name  of  the  terminal 

u3b 

machid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

u3b2 

machid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

u3b5 

machid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

u3bl5 

machid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

ul 

ul(l) 

do  underlining 

umask 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

unalias 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

uname 

uname(l) 

display  the  name  of  the  current  system 

uncompress 

compress(l) 

compress  or  expand  files,  display  expanded  contents 

unexpand 

expand(l) 

expand  TAB  characters  to  SPACE  characters,  and  vice  versa 

unget 

sccs-unget(l) 

undo  a  previous  get  of  an  SCCS  file 

unhash 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

unifdef 

unifdef(l) 

resolve  and  remove  ifdef’ed  lines  from  cpp  input 

uniq 

uniq(l) 

remove  or  report  adjacent  duplicate  lines 

units 

units(l) 

conversion  program 

unixZdos 

unix2dos(l) 

convert  text  file  from  ISO  format  to  IX)S  format 

unlimit 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 
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unload 

unload(l) 

unload  optional  clusters 

unloadc 

unload(l) 

unload  optional  clusters 

unpack 

pack(lV) 

compress  and  expand  files 

unset 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

unsetenv 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

unwbiteout 

unwhiteout(l) 

remove  a  TFS  whiteout  entry 

uptime 

uptime(l) 

show  how  long  the  system  has  been  up 

users 

users(l) 

display  a  compact  list  of  users  logged  in 

ustar 

ustar  (IV) 

process  tape  archives 

UUCP 

uucp(lC) 

system  to  system  copy 

uudecode 

uuencode(lC) 

encode  a  binary  file,  or  decode  its  ASCII  representation 

uuencode 

uuencode(lC) 

encode  a  binary  file,  or  decode  its  ASCII  representation 

uulog 

uucp(lC) 

system  to  system  copy 

uuname 

uucp(lC) 

system  to  system  copy 

uupick 

uuto(lC) 

public  system -to-sy stem  file  copy 

uusend 

uusend(lC) 

send  a  file  to  a  remote  host 

uustat 

uustat(lC) 

UUCP  status  inquiry  and  job  control 

uuto 

uuto(lC) 

public  system-to-system  file  copy 

uux 

uux(lC) 

remote  system  command  execution 

vacation 

vacation(l) 

reply  to  mail  automatically 

val 

sccs-val(l) 

viidate  an  SCCS  file 

vax 

machid(l) 

return  a  true  exit  status  if  the  processor  is  of  the  indicated  type 

vedit 

vi(l) 

visual  display  editor  based  on  ex(l) 

vfontinfo 

vfontinfo(l) 

inspect  and  print  out  information  about  fonts 

vgrind 

vgrind(l) 

grind  nice  program  listings 

vi 

vi(l) 

visual  display  editor  based  on  ex(l) 

vievi^ 

vi(i) 

visual  display  editor  based  on  ex(l) 

vplot 

vplot(l) 

plot  graphics  for  a  Versatec  printer 

vswap 

vswap(l) 

convert  a  foreign  font  file 

vtroff 

vtroff(l) 

troff  to  a  raster  plotter 

vwidth 

vwidth(l) 

make  a  troff  width  table  for  a  font 

w 

w(l) 

who  is  logged  in,  and  what  are  they  doing 

wait 

wait(l) 

wait  for  a  process  to  finish 

wall 

wall(l) 

write  to  all  users  logged  in 

wc 

wc(l) 

display  a  count  of  lines,  words  and  characters 

what 

what(l) 

extract  SCCS  version  information  from  a  file 

whatis 

whatis(l) 

display  a  one-line  summary  about  a  keyword 

whereis 

whereis(l) 

locate  the  binary,  source,  and  manual  page  for  a  command 

which 

which(l) 

locate  a  command;  display  its  pathname  or  alias 

while 

csh(l) 

C  shell  built-in  commands,  see  csh(l) 

who 

who(l) 

who  is  logged  in  on  the  system 

whoami 

whoami(l) 

display  the  effective  current  username 

whois 

whois(l) 

TCP/IP  Internet  user  name  directory  service 

write 

write(l) 

write  a  message  to  another  user 

xargs 

xargs(lV) 

construct  the  arguments  list(s)  and  execute  a  command 

xget 

xseiid(l) 

send  or  receive  secret  mail 

xsend 

xsend(l) 

send  or  receive  secret  mail 

xstr 

xstr(l) 

extract  strings  from  C  programs  to  implement  shared  strings 

yacc 

yacc(l) 

yet  another  compiler-compiler:  parsing  program  generator 

yes 

yes(l) 

be  repetitively  affirmative 

ypcat 

ypcat(l) 

print  values  in  a  NTS  data  base 

ypmatch 

ypmatch(l) 

print  the  value  of  one  or  more  keys  from  a  NIS  map 

yppasswd 

yppasswd(l) 

change  your  network  password  in  the  NIS  database 
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ypwhich 

zcat 


ypwhich(l)  return  hostname  of  NIS  server  or  map  master 

compress(l)  compress  or  expand  files,  display  expanded  contents 
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NAME 

acctcom  -  search  and  print  process  accounting  files 
SYNOPSIS 

acctcom  [  -abfhikmqrtv  ]  [  ~C  jec  ]  [  -e  time  ]  [  -E  time  ]  [  -g  group  ]  [  ~H  factor  ]  [  -I  chars  ] 

[  -I  line  ]  [  -n  pattern  ]  [  -o  output-file  ]  [  -O  ]  [  -s  time  ]  [  -S  time  ]  [  -u  user  ] 

DESCRIPTION 

acctcom  reads  filename,  the  standard  input,  or  /var/adm/pacct,  in  the  form  described  by  acct(5)  and  writes 
selected  records  to  the  standard  output.  Each  record  represents  the  execution  of  one  process.  The  output 
shows  the  COMMAND  NAME.  USER.  TTYNAME,  START  TIME,  END  TIME,  REAL  (SEC),  CPU  (SEC), 
MEAN  SIZE(K),  and  optionally,  F  (the  forklexec  flag:  1  for  fork()  without  exec()),  STAT  (the  system  exit 
status),  HOG  FACTOR,  KCORE  MIN,  CPU  FACTOR,  CHARS  TRNSFD,  and  BLOCKS  READ  (total  blocks 
read  and  written). 

A  is  prepended  to  the  command  name  if  the  command  was  executed  with  super-user  privileges.  If  a 
process  is  not  associated  with  a  known  terminal,  a  ‘?*  is  printed  in  the  TTYNAME  field. 

If  no  filenames  are  specified,  and  if  the  standard  input  is  associated  with  a  terminal  or  /dev/null  (as  is  the 
case  when  using  in  the  shell),  /var/adm/pacct  is  read;  otherwise,  the  standard  input  is  read. 

If  any  filename  arguments  are  given,  they  are  read  in  their  respective  order.  Each  file  is  normally  read  for¬ 
ward,  that  is,  in  chronological  order  by  process  completion  time.  The  file  /var/adm/pacct  is  usually  the 
current  file  to  be  examined;  a  busy  system  may  need  several  such  files  of  which  all  but  the  current  file  are 
found  in  /var/adm/pacct?. 


OPTIONS 

-a 

-b 

-f 

— i 

~k 

-m 

-q 

-r 

-t 

-V 

-C  sec 
-e  time 
-E  time 

-g  group 

-Hfactor 


Show  some  average  statistics  about  the  processes  selected.  The  statistics  will  be  printed 
after  the  output  records. 

Read  backwards,  showing  latest  commands  first.  This  option  has  no  effect  when  the  stan¬ 
dard  input  is  read. 

Print  the  forkfexec  flag  and  system  exit  status  columns  in  the  output.  The  numeric  output  for 
this  option  will  be  in  octal. 

Instead  of  mean  memory  size,  show  the  fraction  of  total  available  CPU  time  consumed  by 
the  process  during  its  execution.  This  “hog  factor”  is  computed  as: 

(total  CPU  time)/(elapsed  time) 

Print  columns  containing  the  I/O  counts  in  the  output. 

Instead  of  memory  size,  show  total  kcore-minutes. 

Show  mean  core  size  (the  default). 

Do  not  print  any  output  records,  just  print  the  average  statistics  as  with  the  -a  option. 

Show  CPU  factor  (user  time/(system-time  +  user-time). 

Show  separate  system  and  user  CPU  times. 

Exclude  column  headings  from  the  output. 

Show  only  processes  with  total  CPU  time,  system  plus  user,  exceeding  sec  seconds. 

Select  processes  existing  at  or  before  time. 

Select  processes  ending  at  or  before  time.  Using  the  same  time  for  both  -S  and  -E  shows 
the  processes  that  existed  at  time . 

Show  only  processes  belonging  to  group.  The  group  may  be  designated  by  either  the  group 
ID  or  group  name. 

Show  only  processes  that  exceed /actor,  where  factor  is  the  “hog  factor”  as  explained  in  the 
-h  option  above. 


w 
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-I  chars  Show  only  processes  transferring  more  characters  than  the  cutoff  number  given  by  chars. 

-I  line  Show  only  processes  belonging  to  terminal  /dev/line. 

—n  pattern  Show  only  commands  matching  pattern  that  may  be  a  regular  expression  as  in  regexp(3). 

-o  ofile  Copy  selected  process  records  in  the  input  data  format  to  ofile;  suppress  standard  output 

printing. 

“O  sec  Show  only  jB-ocesses  with  CPU  system  time  exceeding  sec  seconds. 

-s  time  Select  processes  existing  at  or  after  time ,  given  in  the  format  hr  [ :  min  [ :  ]  ] . 

-S  time  Select  processes  starting  at  or  aftCT  time . 

-u  user  Show  only  processes  belonging  to  user  that  may  be  specified  by:  a  user  ID,  a  login  name  that 

is  then  converted  to  a  user  ID,  a  *#’,  which  designates  only  those  processes  executed  with 
super-user  privileges,  or  ‘?\  which  designates  only  those  processes  associated  with 
unknown  user  IDs. 


FILES 

/etc/passwd 

/var^dm/pacct 

/etc/group 

SEE  ALSO 

ps(l),  su(lV)  acct(2V),  regexp(3),  acct(5),  utmp(5V),  acct(8),  acctcms(8),  acctcon(8),  acctmerg(8), 
acctprc(8),  acctsh(8),  fwtmp(8),  runacct(8) 

BUGS 

acctcom  reports  only  on  processes  that  have  terminated;  use  ps(l)  for  active  processes.  If  time  exceeds  the 
present  time,  then  time  is  interpreted  as  occurring  on  the  previous  day. 
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NAME 

adb  -  general-purpose  debugger 
SYNOPSIS 

adb  [  “W  ]  [  -k  ]  [  -I  dir  ]  [  objectfile  [  corefile  ]  ] 

AVAILABILITY 

adb  is  available  with  the  Debugging  software  installation  option.  Refer  to  Installing  SunOS  4,1  for  infor¬ 
mation  on  how  to  install  optional  software. 

DESCRIPTION 

adb  is  an  interactive,  general-purpose  debugger.  It  can  be  used  to  examine  files  and  provides  a  controlled 
environment  for  the  execution  of  programs. 

objectfile  is  normally  an  executable  program  file,  preferably  containing  a  symbol  table.  If  the  file  does  not 
contain  a  symbol  table,  it  can  stiU  be  examined,  but  the  symbolic  features  of  adb  cannot  be  used.  The 
default  for  objectfile  is  a.out.  corefile  is  assumed  to  be  a  core  image  file  produced  after  executing 
objectfile .  The  default  for  corefile  is  core. 


OPTIONS 

-k  Perform  kernel  memory  mapping;  should  be  used  when  corefile  is  a  system  crash  dump  or 
/dev/mem. 

-w  Create  both  objectfile  and  corefile,  if  necessary,  and  open  them  for  reading  and  writing  so  that 
they  can  be  modified  using  adb. 

-I  dir  specifies  a  directory  where  files  to  be  read  with  $<  or  $«  (see  below)  will  be  sought;  the  default 
is  /usr/lib/adb. 

USAGE 

Refer  to  adb  in  Debugging  Tools  for  more  complete  information  on  how  to  use  adb.  Note:  Some  com¬ 
mands  require  that  you  compile  progams  to  be  debugged  with  the  -go  compiler  flag;  see  cc(l  V)  for  details. 
These  commands  are  not  currently  available  on  Sun-4  systems;  they  are  marked  ‘-go  only’  below. 

Commands 

adb  reads  commands  from  the  standard  input  and  displays  responses  on  the  standard  output.  It  does  not 
supply  a  prompt.  It  ignores  the  QUIT  signal.  INTERRUPT  invokes  the  next  adb  command,  adb  generally 
recognizes  command  input  of  the  form: 

[  address  ]  [,  count  ]  command  [ ;  ] 

address  and  count  (if  supplied)  are  expressions  that  result,  respectively,  in  a  new  current  address,  and  a 
repetition  count,  command  is  composed  of  a  verb  followed  by  a  modifier  or  list  of  modifiers. 

The  symbol  represents  the  current  location.  It  is  initially  zero.  The  default  count  is  ‘1’. 


Verbs 

? 

/ 


$r 

$R 

$x 

$X 

> 

RETURN 

f 


Print  locations  starting  at  address  in  objectfile. 

Print  locations  starting  at  address  in  corefile . 

Print  the  value  of  address  itself. 

Interpret  address  as  a  source  address.  Print  locations  in  objectfile  or  lines  of  source,  as 
appropriate,  -go  only. 

Manage  a  subprocess. 

Print  names  and  contents  of  CPU  registers. 

Print  names  and  contents  of  MC6888 1  registers,  if  any. 

Print  the  names  and  contents  of  FPA  registers  0  through  15,  if  any. 

Print  the  names  and  contents  of  FPA  registers  16  through  31,  if  any. 

Assign  a  value  to  a  variable  or  register. 

Repeat  the  previous  command  with  a  count  of  1.  Increment 
Shell  escape. 
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Modifiers 

Modifiers  specify  the  format  of  command  output.  Each  modifier  consists  of  a  letter,  preceded  by  an  integer 
repeat  count. 

Format  Modifiers 

The  following  format  modifiers  apply  to  the  commands  lyfy@,  and  =.  To  specify  a  format,  follow  the 
command  with  an  optional  repeat  count,  and  the  desired  format  letter  or  letters: 

[v][[r]/...] 

where  v  is  one  of  these  four  command  verbs,  r  is  a  repeat  count,  and /is  one  of  the  format  letters  listed 
below: 

o  increment:  2)  Print  2  bytes  in  octal. 

O  (4)  Print  4  bytes  in  octal, 

q  (2)  Print  in  signed  octal. 

Q  (4)  Print  long  signed  octal, 

d  (2)  Print  in  decimal. 

D  (4)  Print  long  decimal. 

X  (2)  Print  2  bytes  in  hexadecimal. 

X  (4)  Print  4  bytes  in  hexadecimal. 

h  (2)  Print  2  bytes  in  hexadecimal  in  reverse  order.  Sun386i  systems  only. 

H  (4)  Print  4  bytes  in  hexadecimal  in  reverse  order.  Sun386i  systems  only, 

u  (2)  Print  as  an  unsigned  decimal  number. 

U  (4)  Print  long  unsigned  decimal, 

f  (4)  Print  a  single-precision  floating-point  number. 

F  (8)  Print  a  double-precision  floating-point  number. 

e  or  E  (12)  Print  a  96-bit  MC6888 1  extended-precision  floating-point  number.  Sun-2  or  Sun-3 

systems  only. 

b  (1)  Print  the  addressed  byte  in  octal, 

B  (1)  print  the  addressed  byte  in  hexadecimal.  Sun386i  systems  only, 

c  (1)  Print  the  addressed  character. 

C  (1)  print  the  addressed  character  using  *  escape  convention, 

s  (n)  Print  the  addressed  string. 

S  (n)  Print  a  string  using  the "  escape  convention. 

Y  (4)  Print  4  bytes  in  date  format, 

i  (n)  Print  as  machine  instructions, 

M  (rt)  Print  as  machine  instructions  along  with  machine  code.  Sun386i  systems  only, 

z  (n)  Print  with  MC68010  machine  instruction  timings.  Sun-2  or  Sun-3  system  only. 


I 

(0)  Print  the  source  text  line  specified  by  -go  only. 

a 

(0)  Print  the  value  of  in  symbolic  form. 

P 

(4)  Print  the  addressed  value  in  symbolic  form. 

A 

(0)  Print  the  value  of  in  source-symbol  form. 

P 

(4)  print  the  addressed  value  in  source-symbol  form. 

t 

(0)  Tab  to  the  next  appropriate  TAB  stop. 

r 

(0)  Print  a  SPACE, 

n 

(0)PrintaNEWUNE. 

>  j 

(0)  print  the  enclosed  string. 

A 

(0)  Decrement 

+ 

(0)  Increment 

~ 

(0)  Decrement  by  1. 

Modifiers  for  ?  and  1  Only 

1  value  mask 

Apply  mask  and  compare  for  value;  move  to  matching  location. 

L  value  mask 

Apply  mask  and  compare  for  4-byte  value ;  move  to  matching  location. 

w  value 

Write  the  2-byte  value  to  address. 

W  value 

Write  the  4-byte  value  to  address. 

Sun  Release  4.1 


Last  change-  18  February  1988 


17 


ADB(l) 


USER  COMMANDS 


ADB(l) 


mb!  el  fill] 


:  Modifiers 

b  commands 
B  commands 
w  commands 

D 

r 

C5 

Sf 

Sj 

i 

t 

k 

es 

u 

i 

t 

k 

A 

R 

$  Modifiers 
<filename 
«filename 
>filename 
•} 

r 

R 

X 


X 

b 

c 


C 

d 

e 

w 


Map  new  values  for  bl,  el,  fl.  If  the  ?  or  /  is  followed  by  *  then  the  second  segment 
{b2  ,e2  ,/2)  of  the  address  mj^ping  is  changed. 

Set  breakpoint,  execute  commands  when  reached. 

Set  breakpoint  using  source  address,  execute  commands  when  reached,  -go  only. 

Set  a  data  write  breakpoint  at  address  .  Like  b  except  that  the  breakpoint  is  hit  when  the 
program  writes  to  address .  Sun386i  systems  only. 

Delete  breakpoint  at  source  address,  -go  only. 

Run  objectfile  as  a  subprocess. 

The  subprocess  is  continued  with  signal  5. 

Single-step  the  subprocess  with  signal  s. 

Single-step  the  subprocess  with  signal  s  using  source  lines,  -go  only. 

Add  the  signal  specified  by  address  to  the  list  of  signals  passed  directly  to  the  subpro¬ 
cess. 

Remove  the  signal  specified  by  address  from  the  list  implicitly  passed  to  the  subprocess. 
Single-step  the  subprocess  with  signal  s  using  source  lines,  -go  only. 

Like  s,  but  steps  over  subroutine  calls  instead  of  into  them,  Sun386i  systems  only. 
Continue  uplevel,  stopping  after  the  current  routine  has  returned.  Should  only  be  given 
after  the  frame  pointer  has  been  pushed  on  the  stack.  Sun386i  systems  only. 

Add  the  signal  specified  by  address  to  the  list  of  signals  passed  directly  to  the  subpro¬ 
cess 

Remove  the  signal  specified  by  address  from  the  list  implicitly  passed  to  the  subprocess. 
Terminate  the  current  subprocess,  if  any. 

Attach  the  process  whose  process  ID  is  given  by  address.  The  PID  is  generally  preceded 
by  Ot  so  that  it  will  be  interpreted  in  decimal.  Sun386i  systems  only. 

Release  (detach)  the  current  process.  Sun386i  systems  only. 

Read  commands  from  the  file  filename. 

Similar  to  <,  but  can  be  used  in  a  file  of  commands  without  closing  the  file. 

Append  output  to  filename,  which  is  created  if  it  does  not  exist. 

Print  process  ID,  the  signal  which  stopped  the  subprocess,  and  the  registers. 

Print  the  names  and  contents  of  the  general  CPU  registers,  and  the  instruction  addressed 
by  pc. 

On  Sun-3  systems  with  an  MC6888 1  floating-point  coprocessor,  print  the  names  and 
contents  of  the  coprocessor’s  registers. 

On  Sun-3  systems  with  a  Floating  Point  Accelerator  (FPA),  print  the  names  and  contents 
of  FPA  floating-point  registers  0  through  15.  On  Sun4  systems,  print  the  names  and 
contents  of  the  floating-point  registers  0  through  15. 

On  Sun-3  systems  with  an  FPA,  print  the  names  and  contents  of  FPA  registers  16  through 
31.  On  Sun4  systems,  print  the  names  and  contents  of  floating-point  registers  16 
through  31. 

Print  all  breakpoints  and  their  associated  counts  and  commands, 

C  stack  backtrace.  On  Sun4  systems,  it  is  impossible  for  adb  to  determine  how  many 
parameters  were  passed  to  a  function.  The  default  that  adb  chooses  in  a  $c  command  is 
to  show  the  six  parameter  registers.  This  can  be  overridden  by  appending  a  hexadecimal 
number  to  the  ^  command,  specifying  how  many  parameters  to  display.  For  example, 
the  $cf  command  will  print  15  parameters  for  each  function  in  the  stack  trace. 

C  stack  backtrace  with  names  and  (32  bit)  values  of  all  automatic  and  static  variables  for 
each  active  function,  (-go  only). 

Set  the  default  radix  to  address  and  report  the  new  value.  Note:  address  is  interpreted  in 
the  (old)  current  radix.  Thus  ‘10$d’  never  changes  the  default  radix. 

Print  the  names  and  values  of  external  variables. 

Set  the  page  width  for  output  to  address  (default  80). 
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s  Set  the  limit  for  symbol  matches  to  address  (default  255). 

o  All  integers  input  are  regarded  as  octal, 

q  Exit  from  adb. 

V  Print  all  non  zero  variables  in  octal, 

m  Print  the  address  map. 

f  Print  a  list  of  known  source  filenames,  (-go  only), 

p  Print  a  list  of  known  procedure  names,  (-go  only). 

p  {Kernel  debugging)  Change  the  current  kernel  memory  mapping  to  map  the  designated 

user  structure  to  the  address  given  by  _«  (  m  on  Sun386i  systems);  this  is  the  address  of 
the  user’s  proc  structure. 

i  Show  which  signals  are  passed  to  the  subprocess  with  the  minimum  of  adb  interference. 

W  Reopen  objec^le  and  corefile  for  writing,  as  though  the  -w  command-line  argument  had 

been  given. 

1  Set  the  length  in  bytes  (1,  2,  or  4)  of  the  object  referenced  by  :a  and  :w  to  address. 

Default  is  1.  Sun386i  systems  only. 

Variables 

Named  variables  are  set  initially  by  adb  but  are  not  used  subsequently. 

0  The  last  value  printed. 

1  The  last  offset  part  of  an  instruction  source. 

2  The  previous  value  of  variable  1. 

9  The  count  on  the  last  $<  or  $«  command. 

On  entry  the  following  are  set  from  the  system  header  in  the  corefile  or  objectfile  as  appropriate, 
b  The  base  address  of  the  data  segment. 

B  The  number  of  an  address  regist^  that  points  to  the  FPA  page.  Sun-3  systems  only, 

d  The  data  segment  size, 

e  The  entry  point. 

F  On  Sun-3  systems,  a  value  of  *  1’  indicates  FPA  disassembly, 

m  The  ‘magic’  number  (0407, 0410  or  0413). 

s  The  stack  segment  size, 

t  The  text  segment  size. 


Expressions 


& 

integer 

intfrac 

*cccc* 

<name 

symbol 


^symbol 
routine. name 


Unary  Operators 
*exp 
%exp 
-exp 
“exp 
Itexp 


The  value  of  dot. 

The  value  of  dot  incremented  by  the  current  increment 
The  value  of  dot  decremented  by  the  current  increment. 

The  last  address  typed.  (In  older  versions  of  adb,  was  used.) 

A  number.  The  prefixes  Oo  and  OO  indicate  octal;  Ot  and  OT,  decimal;  Ox  and  OX,  hexa¬ 
decimal  (the  default). 

A  floating-point  number. 

ASCII  value  of  up  to  4  characters. 

The  value  of  name ,  which  is  either  a  variable  name  or  a  register  name. 

A  symbol  in  the  symbol  table.  An  initial  will  be  prepended  to  symbol  if  needed. 
Sun-2,  Sun-3,  and  Sun-4  systems  but  not  Sun386i  systems. 

An  external  symbol.  Sun-2,  Sun-3,  and  Sun-4  systems  but  not  Sun386i  systems. 

The  address  of  the  variable  name  in  the  specified  routine  in  the  symbol  table.  If  name  is 
omitted,  the  address  of  the  most  recent  stack  frame  for  routine. 

The  value  of  exp. 

The  contents  of  Icx^ation  exp  in  corefile . 

The  contents  of  location  exp  in  objectfile  (In  older  versions  of  adb,  *@’  was  used). 
Integer  negation. 

Bitwise  complement. 

Logical  negation. 
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ADB(l) 


USER  COMMANDS 


ADB(l) 


"F^jcp 

(CTRL-F)  Translate  program  address  to  source  address,  (-go  only). 

''Aexp 

(CTRL-A)  Translates  source  address  to  program  address,  (-go  only). 

^name 

(Backquote)  Translates  procedure  name  to  sourcefile  address,  (-go  only). 

The  sourcefile  address  for  the  zero-th  line  of  file,  (-go  only). 

Binary  Operators 

Binary  operators  are  left  associative  and  have  lower  precedence  than  unary  operators. 

+ 

Integer  addition. 

- 

Integer  subtraction. 

* 

Integer  multiplication. 

% 

Integer  division. 

& 

Bitwise  conjunction  (“AND”). 

1 

Bitwise  disjunction  (“OR”). 

# 

Ihs  rounded  up  to  the  next  multiple  of  rhs. 

FILES 

/usr/lib/adb 

a.out 

core 


SEE  ALSO 

cc(lV),  dbx(l),  ptrace(2),  a.out(5),  core(5),  kadb(8S) 

Debugging  Tools 
DIAGNOSTICS 

adb,  when  there  is  no  current  command  or  format,  comments  about  inaccessible  files,  syntax  errors,  abnor¬ 
mal  termination  of  commands,  etc.  Exit  status  is  0,  unless  last  command  failed  or  returned  nonzero  status. 

BUGS 

There  does  not  seem  to  be  any  way  to  clear  all  breakpoints. 

adb  uses  the  symbolic  information  in  an  old  and  now  obsolete  format  generated  by  the  -go  flag  of  cc(lV); 
it  should  be  changed  to  use  the  new  format  generated  by  -g. 

Since  no  shell  is  invoked  to  interpret  the  arguments  of  the  :r  command,  the  customary  wild-card  and  vari¬ 
able  expansions  cannot  occur. 

Since  there  is  little  type-checking  on  addresses,  using  a  sourcefile  address  in  an  inappropriate  context  may 
lead  to  unexpected  results. 

The  %cparameter-count  command  is  a  kluge. 
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NAME 

addbib  -  create  or  extend  a  bibliographic  database 
SYNOPSIS 

addbib  [  -a  ]  [  -p  promptfile  ]  database 
AVAILABILITY 

addbib  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  informa¬ 
tion  on  how  to  install  optional  software. 

DESCRIPTION 

When  addbib  starts  up,  answering  y  to  the  initial  Instructions?  prompt  yields  directions;  typing  n  or 
RETURN  skips  them,  addbib  then  prompts  for  various  bibliographic  fields,  reads  responses  from  the  termi¬ 
nal,  and  sends  output  records  to  database.  A  null  response  (just  RETURN)  means  to  leave  out  that  field.  A 
(minus  sign)  means  to  go  back  to  the  previous  field.  A  trailing  backslash  allows  a  field  to  be  continued 
on  the  next  line.  The  repeating  Continue?  prompt  allows  the  user  either  to  resume  by  typing  y  or 
RETURN,  to  quit  the  current  session  by  typing  n  or  q,  or  to  edit  database  with  any  system  editor  (vi(l), 
ex(l),€d(l)), 

OPTIONS 

-a  Suppress  prompting  for  an  abstract;  asking  for  an  abstract  is  the  default.  Abstracts  are  ended  with 
a  CTRL-D. 

-p  promptfile 

Use  a  new  prompting  skeleton,  defined  in  promptfile.  This  file  should  contain  prompt  strings,  a 
TAB,  and  the  key-letters  to  be  written  to  the  database. 

USAGE 

Bibliography  Key  Letters 

The  most  common  key-letters  and  their  meanings  are  given  below,  addbib  insulates  you  from  these  key- 
letters,  since  it  gives  you  prompts  in  English,  but  if  you  edit  the  bibliography  file  later  on,  you  will  need  to 


know  this  information. 

%A 

Author’s  name 

%B 

Book  containing  article  referenced 

%C 

City  (place  of  publication) 

%D 

Date  of  publication 

%E 

Editor  of  book  containing  article  referenced 

%F 

Footnote  number  or  label  (supplied  by  refer) 

%G 

Government  order  number 

%H 

Header  commentary,  printed  before  reference 

%l 

Issuer  (publisher) 

%J 

Journal  containing  article 

%K 

Keywords  to  use  in  locating  reference 

%L 

Label  field  used  by  ~k  option  of  refer 

%M 

Bell  Labs  Memorandum  (undefined) 

%N 

Number  within  volume 

%0 

Other  commentary,  printed  at  end  of  reference 

%P 

Page  number(s) 

%Q 

Corporate  or  Foreign  Author  (unreversed) 

%R 

Report,  paper,  or  thesis  (unpublished) 

Sun  Release  4.1 
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ADDBIB(l) 


%S  Series  title 

%T  Title  of  article  or  book 

%\  Volume  number 

% X  Abstract  —  used  by  roffbib,  not  by  refer 

%Y^  Ignored  by  refer 

EXAMPLE 

Except  for  A,  each  field  should  be  given  just  once.  Only  relevant  fields  should  be  supplied. 
%A  Mark  Twain 

%T  Life  on  the  Mississippi 

%1  Penguin  Books 

%C  New  York 

%D  1978 

SEE  ALSO 

ed(l),  ex(l),  indxbib(l),  lookbib(l),  refer(l),  roffbib(l),  sortbib(l),  vi(l) 
refer  in  Formatting  Documents 
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ADJACENTSCREENS  ( 1 ) 


NAME 

adjacentscreens  -  connect  multiple  screens  to  SunView  window  driver 
SYNOPSIS 

adjacentscreens  [-cl-m]  center-screen  [-ll-rl-tl~b  side-screen  ] ...  -x 
AVAILABILITY 

This  command  is  available  with  the  SunView  User's  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4,1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

adjacentscreens  tells  the  window-driver’s  mouse-pointer  tracking  mechanism  how  to  move  between 
screens  that  contain  windows.  Note:  sunview(l)  must  be  running  on  all  screens  before  adjacentscreens  is 
used.  Once  properly  notified  using  adjacentscreens ,  the  mouse  pointer  slides  from  one  screen  to  another 
as  you  move  the  pointer  past  the  appropriate  edge  of  a  screen. 

OPTIONS 

-c  center-screen 
-m  center-screen 

center-screen  is  the  name  of  a  frame  buffer  device,  such  as  /dev/fb;  all  other  physical  screen- 
positions  are  given  relative  to  this  reference  point.  The  -c  or  -m  flag  is  optional.  If  omitted,  the 
first  argument  is  taken  as  center-screen .  If  no  further  arguments  are  given,  center-screen  has  no 
neighbors. 

-I  side-screen 
-r  side-screen 
-t  side-screen 
-b  side-screen 
-1  side-screen 

side-screen  is  also  a  frame  buffer  device  name,  such  as  /dev/cgone.  The  ~l  flag  indicates  that 
side-screen  is  to  the  left  of  center-screen ;  -r  indicates  that  it  is  to  the  right,  -t  indicates  that 
side-screen  is  on  top  of  (above)  center-screen',  -b  indicates  that  it  is  below.  Each  neighboring 
screen  can  be  specified  as  an  option  on  the  command  line. 

-X  Suppress  the  normal  notification  to  a  side -screen  pointer  tracker  that  center-screen  is  its  only 
neighbor.  This  option  is  useful  if  you  have  a  large  number  of  screens  or  want  exotic  inter-window 
pointer  movements. 

EXAMPLE 

The  following  command: 

example%  adjacentscreens  /dev/fb  -r  /dev/cgone 

sets  up  pointer  tracking  so  that  the  pointer  slides  from  a  monochrome  screen  (/dev/fb)  to  a  color  screen 
(/dev/cgone)  when  the  pointer  moves  off  the  right  hand  edge  of  the  monochrome  display.  Similarly,  the 
pointer  slides  from  the  color  screen  to  the  monochrome  screen  when  the  pointer  moves  off  die  color 
screen’s  left  edge. 

FILES 

/dev/fb 

/dev/cgone 

SEE  ALSO 

sunview(l),  switcher(l) 

BUGS 

Window  systems  on  all  screens  must  be  initialized  before  running  adjacentscreens. 
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APROPOS  (1) 


USER  COMMANDS 


APROPOS  (1) 


NAME 

apropos  -  locate  commands  by  keyword  lookup 

SYNOPSIS 

apropos  keyword. . . 

DESCRIPTION 

apropos  displays  the  man  page  name,  section  number,  and  a  short  description  for  each  man  page  whose 
NAME  line  contains  keyword.  This  information  is  contained  in  the  /usr/man/whatis  database  created  by 
catman(8).  If  catman(8)  was  not  run,  or  was  run  with  the  -n  option,  apropos  fails.  Each  word  is  con¬ 
sidered  separately  and  the  case  of  letters  is  ignored.  Words  which  are  part  of  other  words  are  considered; 
for  example,  when  looking  for  ‘compile’,  apropos  finds  all  instances  of  ‘compiler’  also. 

apropos  is  actually  just  the  -k  option  to  the  n[ian(l)  command. 

Try 

example%  apropos  password 
and 

example%  apropos  editor 

If  the  line  starts  ^filename  {section)  ...’  you  can  do  ‘man  section  filename'  to  display  the  man  page  for 
filename.  Try 

example  %  apropos  format 

and  then 

example%  man  3s  printf 
to  get  the  manual  page  on  the  subroutine  printf( ). 

FILES 

/usr/man/whatis  data  base 
SEE  ALSO 

man(l),  whatis(l),  catman(8) 

DIAGNOSTICS 

/usr/man/whatis:  No  such  file  or  directory 

This  database  does  not  exist.  catman(8)  must  be  run  to  create  it. 
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NAME 

ar  -  create  library  archives,  and  add  or  extract  files 
SYNOPSIS 

ardlnilpIqlrUlx[[  clouv  ]  [  abi  position-name  ]  ]  archive  [  member-file . . .  ] 

SYSTEM  V  SYNOPSIS 

/usr/5biii/ar  [-]  d  I  m  I  p  I  q  I  r  1 1 1  x  [  [  clou  vs  ]  [  abi  position-name  ]  ]  archive  [  member-file.. .  ] 
AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

ar  maintains  groups  of  files  combined  into  a  single  archive  file.  An  archive  file  comprises  a  set  of  member 
files  and  header  information  for  each  file.  The  archive  header  and  the  headers  for  the  file  consist  of  print¬ 
able  characters  (assuming  that  the  names  of  the  files  in  the  archive  contain  printable  characters),  and  are  in 
a  format  portable  across  all  machines.  This  format  is  described  in  detail  in  ar(5)).  If  an  archive  is  com¬ 
posed  of  printable  files,  with  printable  file  names,  the  entire  archive  is  printable. 

ar  is  normally  used  to  create  and  update  library  files  used  by  the  link  editor  ld(l),  but  can  be  used  for  any 
similar  purpose. 

archive  is  the  name  of  the  archive  file,  member-file  is  a  member  file  contained  in  the  archive.  If  this  argu¬ 
ment  is  omitted,  the  command  applies  to  all  entries  in  the  archive.  Member  names  have  a  maximum  of  15 
characters,  except  on  Sun386i  systems,  where  they  have  a  maximum  of  14  characters,  longer  names  are 
truncated. 

SYSTEM  V  DESCRIPTION 

ar  runs  ranlib  after  modifying  an  archive,  so  that  the  symbol  table  member  of  the  archive  is  kept  up-to- 
date. 

OPTIONS 

You  must  indicate  only  one  of:  d,  m,  p,  q,  r,  t,  or  x,  which  may  be  followed  by  one  or  more  Modifiers, 
d  Delete  the  named  files  from  the  archive  file, 
m  Move  the  named  files  to  the  end  of  the  archive. 

p  Print.  If  no  names  are  given,  all  files  in  the  archive  are  written  to  the  standard  output;  if  no  names 

are  given,  only  those  files  are  written,  and  they  are  written  in  the  order  that  they  appear  in  the 
archive. 

q  Quick  append.  Append  the  named  files  to  the  end  of  the  archive  file  without  searching  the  archive 
for  duplicate  names.  Useful  only  to  avoid  quadratic  behavior  when  creating  a  large  archive 
piece-by-piece.  If  this  option  is  used  to  add  a  member  to  an  archive,  and  a  member  with  the  same 
name  as  that  member  already  exists  in  the  archive,  the  old  member  will  not  be  removed;  two 
members  with  the  same  name  will  exist  in  the  archive. 

r  Replace  the  named  files  in  the  archive. 

t  Table  of  contents.  If  no  names  are  given,  all  files  in  the  archive  are  listed;  if  names  are  given, 
only  those  files  are  listed. 

X  Extract.  If  no  names  are  given,  all  files  in  the  archive  are  extracted  into  the  current  directory;  if 
names  are  given,  only  those  files  are  extracted.  In  neither  case  does  x  alter  the  archive  file. 

Modifiers 

c  Create.  Suppress  the  message  that  is  produced  by  default  when  archive  is  created. 

I  Local.  Place  temporary  files  in  the  current  working  directory  rather  than  in  the  default  temporary 
directory,  /tmp. 
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AR(1V) 


USER  COMMANDS 


AR(IV) 


0  Old  date.  When  files  are  extracted  with  the  x  option,  set  the  “last  modified”  date  to  the  date 
recorded  in  the  archive. 

u  Update.  Replace  only  those  files  that  have  changed  since  they  were  put  in  the  archive.  Used  with 
the  r  option. 

V  Veitx)se.  When  used  with  the  r,  d,  m,  or  q  option,  give  a  file-by-file  description  of  the  creation  of 
a  new  archive  file  from  the  old  archive  and  the  constituent  files.  When  used  with  x,  give  a  file- 
by-file  description  of  the  extraction  of  archive  files.  When  used  with  t,  give  a  long  listing  of  infor¬ 
mation  about  the  files.  When  used  with  p,  write  each  member’s  name  to  the  standard  output 
before  writing  the  member  to  the  standard  output. 

a  position-name 

Place  new  files  after  position-name  (position-name  argument  must  be  present).  Applies  only  to 
the  r  and  m  options. 

b  position-name 

Place  new  files  before  position-name  (position-name  argument  must  be  present).  Applies  only  to 
the  r  and  m  options. 

i  position-name 

Identical  to  the  b  modifier. 

SYSTEM  V  OPTIONS 

The  options  may  be  preceded  by 

Modifiers 

s  Force  the  regeneration  of  the  archive  symbol  table  even  if  ar  is  not  invoked  with  a  command  that 
will  modify  the  archive  contents. 

EXAMPLES 

Creating  a  new  archive: 

example  %  ar  rev  archive  file.o 
a  -  fiIe.o 

Adding  to  an  archive: 

example%  ar  rav  file.o  archive  next.c 
a  ~  next.c 

Extracting  from  an  archive: 

example  %  ar  xy  archive  file.o 
X  -  file.o 

example  %  Is  file.o 
fiIe.o 

Seeing  the  table  of  contents: 

example  %  ar  t  archive 

file.o 

next.c 


FILES 

/tmp/v*.  temporary  files 

/tmp 

SEE  ALSO 

ld(l),  lorder(l),  ranlib(l),  ar(5) 

BUGS 

If  the  same  file  is  mentioned  twice  in  an  argument  list,  it  is  put  in  the  archive  twice. 

The  “last-modified”  date  of  a  file  will  not  be  altered  by  the  o  option  unless  the  user  is  either  the  owner  of 
the  extracted  file  or  the  super-user. 
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NAME 

arch  -  display  the  architecture  of  the  current  host 

SYNOPSIS 

arch 
arch  -k 
arch  archname 

DESCRIPTION 

arch  displays  the  application  architecture  of  the  current  host  system. 

Sun  systems  can  be  broadly  classified  by  their  architectures,  which  define  what  executables  will  run  on 
which  machines.  A  distinction  can  be  made  between  kernel  architecture  and  application  architecture  (or, 
commonly,  just  “architecture”).  Machines  that  run  different  kernels  due  to  underlying  hardware  differ¬ 
ences  may  be  able  to  run  the  same  application  programs.  For  example,  the  MC68020-based  Sun-3/160  sys¬ 
tem  and  the  MC68030-based  Sun-3/80  system  run  different  SunOS  kernels,  but  can  execute  the  same  appli¬ 
cations.  These  machines  could  be  described  as  having  “the  same  application  architecture”  but  “different 
kernel  architectures.” 

Executing  arch  will  display  the  application  architecture  of  the  machine,  such  as  sun3,  sun4,  etc.  All 
machines  of  the  same  application  architecture  will  execute  the  same  application  programs,  or  user  binaries. 

Current  Architectures 


Application  architecture 

Kernel  architecture 

Current  Sun  System  Models 

sun3 

sun3 

3/50, 3/60, 3/75, 3/110, 

3/140, 3/160, 3/180, 3/260, 3/280 

sun3 

sun3x 

3/80, 3/460.  3/470, 3/480 

sun4 

sun4 

4/110,4/260,4/280, 
SPARCsystem  330, 
SPARCserver  390 

sun4 

sun4c 

SPARCstation  1 

sun386 

sun386 

3861/150, 386i/250 

Display  the  kernel  architecture,  such  as  sun3,  sun3x,  sun4c,  etc.  This  defines  which  specific 
SunOS  kernel  will  run  on  the  machine,  and  has  implications  only  for  programs  that  depend  on 
the  kernel  explicitly  (for  example,  ps(l),  vmstat(8),  etc.). 

Return  “true”  (exit  status  0)  if  application  binaries  for  archname  can  run  on  the  current  host 
system,  otherwise,  return  “false”  (exit  status  1).  This  is  the  preferred  method  for  installation 
scripts  to  determine  the  environment  of  the  host  machine;  that  is,  which  architecture  of  a 
multi-architecture  release  to  install  on  this  machine,  archname  must  be  a  valid  application 
architecture. 


OPTIONS 

-k 


archname 


SEE  ALSO 

mach(l),  machid(l) 

Installing  SunOS  4.1 
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AS(1) 


NAME 

as  -  Sun-1,  Sun-2  and  Sun-3,  Sun-4  and  Sun386i  assemblers 
SUN-1,  SUN-2  and  SUN-3  SYNOPSIS 

as  [  -L  ]  [  -R  ]  [  ~o  objfile  ]  [  -d2  ]  [  -h  ]  [  -j  ]  [  ~J  ]  [  -O  ]  [  -mc68010  ]  [  -inc68020  ]  filename 
SUN-4  SYNOPSIS 

as  [  “L  ]  [  -R  ]  [  -0  objfile  ]  [  -0[n]  ]  [  -P  [  [  -Ipath  ]  [  -\)name  ]  [  -Dname=def]  [  -Vname  ]]...] 

[  — S[C]  ]  filename  . . . 

Sun386i  SYNOPSIS 

as  [  -k  ]  [  -o  objfile  ]  [  -R  ]  [  ~V  ]  [  -1386  ] 

DESCRIPTION 

as  translates  the  assembly  source  filename  into  an  executable  object  file,  objfile.  The  Sun-4  assembler 

recognizes  the  filename  argument  as  the  standard  input. 

All  undefined  symbols  in  the  assembly  are  treated  as  global. 

The  output  of  the  assembly  is  left  in  the  file  objfile. 

OPTIONS 

The  following  options  are  common  to  all  Sun  architectures.  Options  for  specific  Sun  architecuires  are 

listed  below. 

-L  Save  defined  labels  beginning  with  an  L,  which  are  normally  discarded  to  save  space  in  the  resul¬ 
tant  symbol  table.  The  compilers  generate  many  such  temporary  labels. 

-R  Make  the  initialized  data  segment  read-only  by  concatenating  it  to  the  text  segment.  This  elim¬ 
inates  the  need  to  run  editor  scripts  on  assembly  code  to  make  initialized  data  read-only  and 
shared. 

-o  objfile 

The  next  argument  is  taken  as  the  name  of  the  object  file  to  be  produced.  If  the  -o  flag  is  not 
used,  the  object  file  is  named  a. out. 

Sun-1,  Sun-2  and  Sun-3  Options 

-d2  Instruction  offsets  that  involve  forward  or  external  references,  and  with  unspecified  size,  are  two 
bytes  long,  (See  also  the  -j  option.) 

-h  Suppress  span-dependent  instruction  calculations.  Restrict  branches  to  medium  length.  Force 
calls  to  take  the  most  general  form.  This  option  is  used  when  the  assembly  must  be  minimized, 
even  at  the  expense  of  program  size  and  run-time  performance.  It  results  in  a  smaller  and  faster 
program  than  one  produced  by  the  -J  option,  but  some  very  large  programs  may  be  unable  to  use 
it  due  to  the  limits  of  medium-length  branches, 

-j  Use  short  (pc-relative)  branches  to  resolve  jump  and  jump-to-subroutine  instructions  to  external 
routines.  This  is  for  compact  programs  for  which  the  -d2  option  is  inappropriate  due  to  large- 
program  relocation. 

-J  Suppress  span-dependent  instruction  calculations  and  force  branches  and  calls  to  take  the  most 
general  form.  This  is  useful  when  assembly  time  must  be  minimized,  even  at  the  expense  of  pro¬ 
gram  size  and  run-time  performance. 

-O  Perform  span-dependent  instruction  resolution  over  entire  files  rather  than  just  individual  pro¬ 
cedures. 

Sun-4  Options 

-0[/i]  Enable  peephole  optimization  corresponding  to  optimization  level  n  (1  if  n  not  specified)  of  the 
Sun  high-level  language  compilers.  This  option  can  be  used  safely  only  when  assembling  code 
produced  by  a  Sun  compiler. 

-P  Run  cpp(l),  the  C  preprocessor,  on  the  files  being  assembled.  The  preprocessor  is  run  separately 
on  each  input  file,  not  on  their  concatenation.  The  preprocessor  output  is  passed  to  the  assembler. 
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-Ipath 

-Dname 

-Dname=def 

-liname 

When  -P  is  in  effect,  these  cpp(l)  options  are  passed  to  the  C  preprocessor,  without  interpretation 
by  as.  Otherwise,  they  are  ignored. 

-S[C]  Produce  a  disassembly  of  the  emitted  code  to  the  standard  output.  This  is  most  useful  in  combina¬ 
tion  with  the  -O  option,  to  review  optimized  code.  Adding  the  character  C  to  the  option  prevents 
comment  lines  firom  appearing  in  the  output. 

Suii386i  Options 

-k  Create  position  independent  code.  Called  by  cc  ~pic. 

-V  Write  the  version  number  of  the  assembler  being  run  on  the  standard  error  output. 

-i386  Confirm  that  this  output  is  intended  for  an  80386  processor. 

FILES 

/tmp/as*  default  temporary  file 

SEE  ALSO 

adb(l),  cpp(l),  dbx(l),  Id(l),  a.out(5)  coff(5) 

Sun-4  Assembly  Language  R^erence 
Sun-3  Assembly  Language  Reference 

BUGS 

The  Sun  Pascal  compiler  qualifies  a  nested  procedure  name  by  chaining  the  names  of  the  enclosing  pro¬ 
cedures.  This  sometimes  results  in  names  long  enough  to  abort  the  assembler,  which  currendy  limits 
identifiers  to  512  characters  (the  Sun-4  assembler  does  not  have  this  restriction). 

Sun386i  WARNINGS 

There  can  be  only  one  forward-reference  to  a  symbol  per  arithmetic  expression. 
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NAME 

at,  batch  -  execute  a  command  or  script  at  a  specified  time 
SYNOPSIS 

at  [  -csm  ]  [  -qqueue  ]  time  [  date  ]  [  +  increment  ]  [  script  ] 
at  -r  jobs.,. 

Sit -I  [Jobs...  ] 

batch  [  -csm  ]  [  script  ] 

DESCRIPTION 

at  and  batch  read  commands  from  standard  input  to  be  executed  at  a  later  time,  at  allows  you  to  specify 
when  the  commands  should  be  executed,  while  jobs  queued  with  batch  will  execute  as  soon  as  the  system 
load  level  permits,  script  is  the  name  of  a  file  to  be  used  as  command  input  for  the  Bourne  shell,  sh(l),  the 
C  shell,  csh(l),  or  an  arbitrary  shell  specified  by  the  SHELL  environment  variable.  If  script  is  omitted, 
command  input  is  accepted  from  the  standard  input. 

Standard  output  and  standard  error  output  are  mailed  to  the  user  unless  they  are  redirected  elsewhere.  The 
shell  environment  variables,  current  directory,  and  umask(2V)  are  retained  when  the  commands  are  exe¬ 
cuted.  Open  file  descriptors,  traps,  and  priority  are  lost. 

Users  are  permitted  to  use  at  if  their  name  appears  in  the  file  /var/spool/cron/at.allow.  If  that  file  does  not 
exist,  the  file  /var/spool/cron/at.deny  is  checked  to  determine  if  the  user  should  be  denied  access  to  at.  If 
neither  file  exists,  only  the  super-user  is  allowed  to  submit  a  job.  If  at.deny  is  empty,  global  usage  is  per¬ 
mitted.  The  allow/deny  files  consist  of  one  user  name  per  line. 

The  time  may  be  specified  as  1,  2,  or  4  digits.  One  and  two  digit  numbers  are  taken  to  be  hours,  four  digits 
to  be  hours  and  minutes.  The  time  may  alternately  be  specified  as  two  numbers  separated  by  a  colon, 
meaning  hounminute.  A  suffix  am  or  pm  may  be  appended;  otherwise  a  24-hour  clock  time  is  understood. 
The  suffix  Zulu  may  be  used  to  indicate  GMT.  The  special  names  noon,  midnight,  now,  and  next  are  also 
recognized. 

An  optional  date  may  be  specified  as  either  a  month  name  followed  by  a  day  number  (and  possibly  year 
number  preceded  by  an  optional  comma)  or  a  day  of  the  week  (fully  spelled  or  abbreviated  to  three  charac¬ 
ters).  Two  special  “days”,  today  and  tomorrow  are  recognized.  If  no  date  is  given,  today  is  assumed  if 
the  given  hour  is  greater  than  the  current  hour  and  tomorrow  is  assumed  if  it  is  less.  If  the  given  month  is 
less  than  the  current  month  (and  no  year  is  given),  next  year  is  assumed. 

The  optional  increment  is  simply  a  number  suffixed  by  one  of  the  following:  minutes,  hours,  days,  weeks, 
months,  or  years.  (The  singular  form  is  also  accepted.) 

Thus  legitimate  commands  include: 

at  0815am  Jan  24 
at  8: 15am  Jan  24 
at  now  +  1  day 
at  5  pm  Friday 

at  and  batch  write  the  job  number  and  schedule  time  to  standard  error. 

batch  submits  batch  jobs  to  queue  b;  this  “batch”  queue  is  for  jobs  to  be  run  as  soon  as  possible.  A  job 
submitted  to  b  is  scheduled  to  run  immediately  and  its  arguments  will  not  be  interpreted  as  time,  date,  or  + 
increment. 

batch  is  similar  to  ‘at  now’,  but  does  not,  for  example,  go  into  the  same  queue  or  respond  with  the  error 
message  ‘too  late’. 

oraoNs 

-c  C  shell,  csh  is  used  to  execute  script. 

-s  Standard  (Bourne)  shell,  sh  is  used  to  execute  the  job.  By  default,  the  SHELL  environment 

variable  determines  which  shell  to  use. 
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-m  Mail.  Send  mail  after  the  job  has  been  run,  even  if  the  job  completes  successfully. 

-qqueue  Submit  the  job  in  queue  queue  rather  than  the  default  queue  a.  The  valid  queues  are  a  through 
z.  batch  submits  jobs  in  queue  b.  Queue  c  is  reserved  for  cron(8)  and  jobs  cannot  be  submit¬ 
ted  to  that  queue. 

~r  jobs  . . .  Remove  the  specified  Jobs  previously  scheduled  by  at  or  batch.  The  job  numbers  are  the 
numbers  of  the  jobs  given  to  you  previously  by  the  at  or  batch  commands.  You  can  only 
remove  your  own  jobs  unless  you  are  the  super-user. 

-I  [jobs.,.] 

If  jobs  is  specified,  print  the  queue  entry  for  those  jobs',  if  jobs  is  not  specified,  print  the  queue 
entries  for  all  jobs  for  the  user. 

ENVIRONMENT 

If  neither  at.aIlow  nor  at.deny  exists,  only  the  super-user  is  allowed  to  submit  a  job.  If  at.deny  is  present, 
but  empty,  global  usage  is  permitted.  The  allow/deny  files  consist  of  one  user  name  per  line. 

EXAMPLES 

Unless  a  script  is  specified,  the  at  and  batch  commands  read  from  standard  input  the  commands  to  be  exe¬ 
cuted  at  a  later  time,  sh  and  csh  provide  different  ways  of  specifying  standard  input.  Within  your  com¬ 
mands,  it  may  be  useful  to  redirect  standard  output. 

This  sequence  can  be  used  at  a  terminal: 

batch 

nroff filename  >  outfile 

CTRL-D  (hold  down  ‘control’  and  depress  ‘D’) 

This  sequence,  which  demonstrates  redirecting  standard  error  to  a  pipe,  is  useful  in  a  shell  procedure  (the 
sequence  of  output  redirection  specifications  is  significant): 

batch  «1 

nroff  filename  2>&1  >  outfile  \  mail  loginid 

f 

To  have  a  job  reschedule  itself,  invoke  at  from  within  the  shell  procedure,  by  including  code  similar  to  the 
following  within  the  shell  file: 

at  1900  thursday  next  week  shellfile 


FILES 

/var/spool/cron 

/var/spool/cron/at.allow 

/var/spool/cron/at.deny 

/var/spool/cron/atjobs 


main  cron  directory 
list  of  allowed  users 
list  of  denied  users 
spool  area 


SEE  ALSO 

atq(l),  atrm(l),  csh(l),  kill(l),  mail(l),  nice(l),  ps(l),  sh(l),  umask(2V),  cron(8) 


DIAGNOSTICS 

Complaints  about  various  syntax  errors  and  times  out  of  range. 


BUGS 

If  the  system  crashes,  mail  stating  that  the  job  was  not  completed  is  not  sent  to  the  user. 
Shell  interpreter  specifiers  (such  as,  !/bin/csh)  in  the  beginning  of  script  are  ignored. 
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NAME 

atq  -  display  the  queue  of  jobs  to  be  run  at  specified  times 
SYNOPSIS 

atq  [  -c ]  [ -n ]  username.. . 

DESCRIPTION 

atq  prints  the  queue  of  jobs,  created  with  the  at(l)  command,  that  are  waiting  to  be  run  at  later  date. 

With  no  flags,  the  queue  is  sorted  in  chronological  order  of  execution. 

If  no  usernames  are  specified,  the  entire  queue  is  displayed;  otherwise,  only  those  jobs  belonging  to  the 
named  users  are  displayed. 

OPTIONS 

~c  Creation  time.  Sorted  the  queue  by  the  time  that  the  at  command  was  given,  the  most  recently 
created  job  first. 

--11  Number  of  jobs.  Print  the  total  number  of  jobs  currently  in  the  queue.  Do  not  list  them. 

FILES 

/var/spool/cron  spool  area 
SEE  ALSO 

at(l),  atrm(l),  cron(8) 
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NAME 

atrm  -  remove  jobs  spooled  by  at  or  batch 
SYNOPSIS 

atrm  [ -f i  ]  [ - ]  [ job-number  ] . . .  [  username  ] ... 

DESCRIPTION 

atrm  removes  delayed-execution  jobs  that  were  created  with  the  at(l)  command.  The  list  of  jobs  can  be 
displayed  by  atq(l). 

atrm  removes  each  job-number  you  specify,  and/or  all  jobs  belonging  to  username,  provided  that  you  own 
the  indicated  jobs. 

Jobs  belonging  to  other  users  can  only  be  removed  by  the  super-user. 

OPTIONS 

-f  Force.  All  information  regarding  the  removal  of  the  specified  jobs  is  suppressed. 

-i  Interactive,  atrm  asks  if  a  job  should  be  removed;  a  response  of  y  verifies  that  the  job  is  to  be 

removed. 

-  Remove  jobs  that  were  queued  by  the  current  user.  If  invoked  by  the  super-user,  the  entire  queue 
will  be  flushed. 

FILES 

/var/spool/cron  spool  area 
SEE  ALSO 

at(l),  atq(l),  cron(8) 
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NAME 

awk  -  pattern  scanning  and  processing  language 
SYNOPSIS 

awk  [  -f  program-file  ]  [  -Fc  ]  [  program  ]  [  variable  rvalue  . . .  ]  [filename , , .  ] 

DESCRIPTION 

awk  scans  each  of  its  mpwi  filenames  for  lines  that  match  any  of  a  set  of  patterns  specified  in  program. 
The  input  filenames  are  read  in  order;  the  standard  input  is  read  if  there  are  no  filenames.  The  filename 
means  the  standard  input 

The  set  of  patterns  may  either  appear  literally  on  the  command  line  as  program,  or,  by  using  the  *--f 
program-file"  option,  the  set  of  patterns  may  be  in  a  program  file;  a  program-file  of  means  the  standard 
input.  If  the  program  is  specified  on  the  command  line,  it  should  be  enclosed  in  single  quotes  (')  to  protect 
it  from  the  shell. 

awk  variables  may  be  set  on  the  command  line  using  arguments  of  the  form  variable =value.  This  sets  the 
awk  variable  variable  to  value  before  the  first  record  of  the  next  filename  argument  is  read. 

With  each  pattern  in  program  there  can  be  an  associated  action  that  will  be  performed  when  a  line  of  a 
filename  matches  the  pattern.  See  the  discussion  below  for  the  format  of  input  lines  and  the  awk  language. 
Each  line  in  each  input  filename  is  matched  against  the  pattern  portion  of  every  pattern-action  statement; 
the  associated  action  is  performed  for  each  matched  pattern. 

OPTIONS 

-f  program-file 

Use  the  contents  of  program-file  as  the  source  for  the  program. 

-Fc  Use  the  character  c  as  the  field  separator  (FS)  character.  See  the  discussion  of  FS  below. 

USAGE 

Input  Lines 

An  input  line  is  made  up  of  fields  separated  by  white  space.  The  field  separator  can  be  changed  by  using 
FS  —  see  Special  Variable  Names  below.  Fields  are  denoted  $1,  $2,  and  so  forth.  $0  refers  to  the  entire 
line. 

Pattern-action  Statements 

A  pattern-action  statement  has  the  form 
pattern  {  action  } 

A  missing  action  means  copy  the  line  to  the  output;  a  missing  pattern  always  matches. 

Action  Statements 

An  action  is  a  sequence  of  statements.  A  statement  can  be  one  of  the  following: 

if  ( conditional )  statement  [  else  statement  ] 

while  (  conditional )  statement 

for  ( expression  ;  conditional ;  expression )  statement 

break 

continue 

{  [  statement  ] . . .} 

variable  ^expression 

print  [  expression-list  ]  [  >  expression  ] 

Sprintf format  [ ,  expression-list  ]  [  >  expression  ] 

next  skip  remaining  patterns  on  this  input  line 

exit  skip  the  rest  of  the  input 

Format  of  the  awk  Language 

statements  are  terminated  by  semicolons,  NEWLINE  characters  or  right  braces.  An  empty  expression-list 
stands  for  the  whole  line. 
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expressions  take  on  string  or  numeric  values  as  appropriate,  and  are  built  using  the  operators 

and  concatenation  (indicated  by  a  blank).  The  C  operators  ++  ,  —  ,  ~  ,  *z=  ,  /=  ,  and  %=  are  also 

available  in  expressions. 

variable  may  be  scalars,  array  elements  (denoted  x  [  i])  or  fields.  Variables  are  initialized  to  the  null 
string.  Array  subscripts  may  be  any  string,  not  necessarily  numeric,  providing  a  form  of  associative 
memory.  String  constants  are  quoted 

The  print  statement  prints  its  arguments  on  the  standard  output  (or  on  a  file  if  >filename  is  present), 
separated  by  the  current  output  field  separator,  and  terminated  by  the  output  record  separator.  The  printf 
statement  formats  its  expression  list  according  to  the  format  template  format  (see  printf(3V)  for  a  descrip¬ 
tion  of  the  formatting  control  characters). 

Built  In  Functions 

The  built-in  function  length  returns  the  length  of  its  argument  taken  as  a  string,  or  of  the  whole  line  if  no 
argument.  There  are  also  built-in  functions  exp,  log,  sqrt,  and  int,  where  int  truncates  its  argument  to  an 
integer.  'substr(  s,  m,  n  )’  returns  the  n-characler  substring  of  s  that  begins  at  position  m.  *sprintf  ifor- 
maty  expressioHy  expression,  . . .)’  formats  the  expressions  according  to  the  printf  format  given  by  format, 
and  returns  the  resulting  string. 

Patterns 

Patterns  are  arbitrary  Boolean  combinations  (1, 1 1  ,  &&,  and  parentheses)  of  regular  expressions  and  rela¬ 
tional  expressions.  Regular  expressions  must  be  surrounded  by  slashes  and  are  as  in  egrep  (see  grep(l  V)), 
Isolated  regular  expressions  in  a  pattern  apply  to  the  entire  line.  Regular  expressions  may  also  occur  in 
relational  expressions. 

A  pattern  may  consist  of  two  patterns  separated  by  a  comma;  in  this  case,  the  action  is  performed  for  all 
lines  between  an  occurrence  of  the  first  pattern  and  the  next  occurrence  of  the  second. 

A  relational  expression  is  one  of  the  following: 

expression  matchop  regular-expression 
expression  relop  expression 

where  a  relop  is  any  of  the  six  relational  operators  in  C,  and  a  matchop  is  either  “  (contains)  or  T  (does  not 
contain).  A  conditional  is  an  arithmetic  expression,  a  relational  expression,  or  a  Boolean  combination  of 
these. 

The  special  pattern  BEGIN  may  be  used  to  capture  control  before  the  first  input  line  is  read,  in  which  case 
BEGIN  must  be  the  first  pattern.  The  special  pattern  END  may  be  used  to  capture  control  after  the  last  input 
line  is  read,  in  which  case  END  must  be  the  last  pattern. 

Special  Variable  Names 

A  single  character  c  may  be  used  to  separate  the  fields  by  starting  the  program  with 
BEGIN  {FS  =  "c"  } 
or  by  using  the  -Fc  option. 

Other  variable  names  with  special  meanings  include  NF,  the  number  of  fields  in  the  current  record;  NR,  the 
ordinal  number  of  the  current  record;  FILENAME,  the  name  of  the  current  input  file;  OFS,  the  output  field 
separator  (default  blank);  ORS,  the  ouq)ut  record  separator  (default  NEWLINE);  and  OFMT,  the  output  for¬ 
mat  for  numbers  (default  %.6g). 

EXAMPLES 

Print  lines  longer  than  72  characters: 
length  >  72 

Print  first  two  fields  in  opposite  order: 

{  print  $2,  $1 } 
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Add  up  first  column,  print  sum  and  average: 

{s+=  $1} 

END  {  print  "sum  is",  s,  "  average  is",  s/NR  } 

Print  fields  in  reverse  order: 

{  for  (i  -  NF;  i  >  0;  — i)  print  $i } 

Print  all  lines  between  start/stop  pairs: 

/start/,  /stop/ 

Print  all  lines  whose  first  field  is  different  from  previous  one: 

$1  !=  prev  {  print;  prev  =  $1 } 

SEE  ALSO 

grep(lV),  lex(l),  sed(lV),  printf(3V) 

Editing  Text  Files 

A.  V.  Aho,  B.  W.  Keminghan,  P.  J.  Weinberger,  The  AWK  Programming  Language  Addison-Wesley, 
1988. 

NOTES 

The  awk  command  is  not  changed  to  support  8-bit  symbol  names,  as  this  would  produce  awk  source  code 
that  is  not  portable  between  systems. 

BUGS 

Input  white  space  is  not  preserved  on  output  if  fields  are  involved. 

There  are  no  explicit  conversions  between  numbers  and  strings.  To  force  an  expression  to  be  treated  as  a 
number  add  0  to  it;  to  force  it  to  be  treated  as  a  string  concatenate  the  null  string  ("  ")  to  it. 

There  is  no  escape  sequence  that  prints  a  double-quote.  A  workaround  is  to  use  .  the  sprintf  (see 
printf(3V))  function  to  store  the  character  into  a  variable  by  its  ASCII  sequence. 

dq  =  sprintfC  %c",  34) 

Syntax  errors  result  in  the  cryptic  message  ‘awk:  bailing  out  near  line  V. 
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NAME 

banner  -  display  a  string  in  large  letters 
SYNOPSIS 

/usr/5bin/banner  strings 
AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

banner  prints  its  arguments  (each  up  to  10  characters  long)  in  large  letters  on  the  standard  output. 

SEE  ALSO 

echo(lV) 

BUGS 

When  banner  is  used  with  characters  from  the  top  half  of  the  Latin- 1  character  set  (see  iso_8859_l(7)), 
each  character  is  mapped  to  a  best  approximation  for  that  character  based  on  the  available  ASCII  character 
shapes  (for  example,  diacritical  marks  are  removed). 
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NAME 

bar  -  create  tape  archives,  and  add  or  extract  files 

SYNOPSIS 

bar  [  —  ]  crxtu  [  014578feovwbXIFmhpBisHSUZRTIN  ]  [  bar-file  ]  [  blocksize  ]  [  exclude-file  ] 

[  string  ]  [  target _directory  ]  [  user  id  ]  [  include-file  Ifilenamel  . . . 

[  -C  dir  filename  ...  ] . . . 

DESCRIPTION 

bar  archives  and  extracts  multiple  files  onto  a  single  bar,  file  archive,  called  a  bar-file.  It  is  quite  similar 
to  tar(5),  but  it  has  additional  function  modifiers,  can  read  and  write  multiple  volumes,  and  writes  and 
reads  a  format  that  is  incompatible  with  tar  (see  bar (5)).  A  bar-file  is  usually  a  magnetic  tape,  but  it  can 
be  any  file,  bar’s  actions  are  controlled  by  the  first  argument,  the  key,  a  string  of  characters  containing 
exactly  one  function  letter  from  the  set  rxtuc,  and  one  or  more  of  the  optional  function  modifiers  listed 
below.  Other  arguments  to  bar  are  file  or  directory  names  that  specify  which  files  to  archive  or  extract.  In 
all  cases,  the  appearance  of  a  directory  name  refers  recursively  to  the  files  and  subdirectories  of  that  direc¬ 
tory. 

FUNCTION  LETTERS 

c  Create  a  new  bar-file  and  write  the  named  files  onto  it. 

r  Write  the  named  files  on  the  end  of  the  bar-file.  Note:  this  option  does  not  work  with  quarter-inch 
archive  tapes. 

X  Extract  the  named  files  from  the  bar-file.  If  a  named  file  matches  a  directory  with  contents  written  onto 
the  tape,  this  directory  is  (recursively)  extracted.  The  owner,  modification  time,  and  mode  are  restored 
(if  possible).  If  no  filename  arguments  are  given,  all  files  in  the  archive  are  extracted.  Note:  if  multiple 
entries  specifying  the  same  file  are  on  the  tape,  the  last  one  overwrites  all  earlier  versions. 

t  List  the  table  of  contents  of  the  bar-file. 

u  Add  the  named  files  to  the  bar-file  if  they  are  not  there  or  if  they  have  been  modified  since  they  were 
last  archived.  Note:  this  option  does  not  work  with  quarter-inch  archive  tapes. 

FUNCTION  MODIFIERS 
014578 

Select  an  alternate  drive  on  which  the  tape  is  mounted.  The  numbers  2,  3,  6,  and  9  do  not  specify  valid 
drives.  The  default  is  /dev/rmtS. 

f  Use  the  next  argument  as  the  name  of  the  bar-file.  If  f  is  omitted,  use  the  device  indicated  by  the  TAPE 
environment  variable,  if  set.  Otherwise,  use  /dev/rmt8  by  default.  If  bar-file  is  given  as  bar 
writes  to  the  standard  output  or  reads  from  the  standard  input,  whichever  is  appropriate.  Thus,  bar  can 
be  used  as  the  head  or  tail  of  a  filter  chain,  bar  can  also  be  used  to  copy  hierarchies  with  the  command: 

example  %  cd  fromdir;  bar  cf  - .  |  (cd  todir;  bar  xfBp  -) 

e  If  any  unexpected  errors  occur  bar  exits  immediately  with  a  positive  exit  status. 

0  Suppress  information  specifying  owner  and  modes  of  directories  which  bar  normally  places  in  the 
archive.  Such  information  makes  former  versions  of  bar  generate  an  error  message  like: 

filename.'  cannot  create 
when  they  encounter  it. 

V  Verbose.  Normally  bar  does  its  work  silently;  the  v  option  displays  the  name  of  each  file  bar  treats, 
preceded  by  the  function  letter.  When  used  with  the  t  function,  v  displays  the  bar-file  entries  in  a  form 
similar  to  Ts-l  *. 


/  \ 
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w  Wait  for  user  confirmation  before  taking  the  specified  action.  If  you  use  w,  bar  displays  the  action  to 
he  taken  followed  by  the  file  name,  and  then  waits  for  a  y  response  to  proceed.  No  action  is  taken  on 
the  named  file  if  you  type  anything  other  than  a  line  beginning  with  y. 

b  the  next  argument  as  the  blocking  factor  for  tape  records.  The  default  blocking  factor  is  20  blocks. 
The  block  size  is  determined  automatically  when  reading  tapes  (key  letters  x  and  t).  This  determination 
of  the  blocking  factor  may  be  fooled  when  reading  from  a  pipe  or  a  socket  (see  the  B  key  letter  below). 
The  maximum  blocking  factor  is  determined  only  by  the  amount  of  memory  available  to  bar  when  it  is 

run.  Larger  blocking  factors  result  in  better  throughput,  longer  blocks  on  nine-track  tapes  and  better 
media  utilization.  ’ 

X  Use  the  next  argument  as  a  file  containing  a  list  of  named  files  (or  directories)  to  be  excluded  from  the 
bar-file  when  using  the  key  letters  ‘c\  ‘x’,  or  ‘t’.  Multiple  X  arguments  may  be  used,  with  one 
exclude-file  per  argument. 

I  Display  error  messages  if  all  links  to  archived  files  cannot  be  resolved.  If  1  is  not  used,  no  error  mes¬ 
sages  are  printed. 

F  With  one  F  argument  specified,  exclude  all  directories  named  sees  from  bar-file.  With  two  arguments 

FF,  exclude  all  directories  named  SCCS,  all  files  with  .o  as  their  suffix,  and  all  files  named  errs  core 
and  a.out. 

m  Do  not  extract  modification  times  of  extracted  files.  The  modification  time  will  be  the  time  of  extrac¬ 
tion. 

h  Follow  symbolic  links  as  if  they  were  normal  files  or  directories.  Normally,  bar  does  not  follow  sym¬ 
bolic  links. 

p  Restore  the  named  files  to  their  original  modes,  ignoring  the  present  umask(2V).  Setuid  and  sticky 
information  are  also  extracted  if  you  are  the  super-user.  This  option  is  only  useful  with  the  x  key  letter. 

B  Force  bar  to  perform  multiple  reads  (if  necessary)  so  as  to  read  exactly  enough  bytes  to  fill  a  block. 
This  option  exists  so  that  bar  can  work  across  the  Ethernet,  since  pipes  and  sockets  return  partial 
blocks  even  when  more  data  is  coming. 

i  Ignore  directory  checksum  errors. 

s  Force  the  ownership  of  extracted  files  to  match  the  bar  process’s  effective  user  ID  and  group  ID. 

H  The  string  of  up  to  128  characters  is  to  be  used  as  a  volume  header  ID.  A  volume  header  is  written  to 
each  volume  of  the  archive  when  the  c  function  letter  is  specified.  See  bar(5)  for  the  volume  header’s 
format. 

Use  of  the  H  function  modifier  when  creating  an  archive  allows  bar  to  read  volumes  out  of  sequence. 
When  extracting  a  file  that  spans  volumes,  bar  will  identify  the  tape(s)  it  needs  to  extract  the  entire  file. 
If  the  wrong  volume  is  inserted,  bar  issues  a  warning  and  prompts  again  for  the  correct  volume. 

S  Place  files  specified  for  extraction  in  this  target  directory  when  used  with  the  x  function  letter. 

U  Specify  the  user  ID  in  the  volume  header  when  creating  archive,  when  the  H  function  modifier  is  used. 
If  the  c  function  letter  is  specified  and  a  volume  header  exists,  bar  will  verify  that  the  user  ids  match 
before  overwriting  bar-file  if  the  N  modifier  is  specified. 

Z  Specify  compression,  bar  will  compress  files  when  used  with  the  c  function  letter  and  will  decompress 
files  when  used  with  the  x  function  letter,  bar  will  neither  compress  a  compressed  file,  nor  decompress 
a  decompressed  file. 

R  Read  the  volume  header  and  print  the  information  to  stdout, 

N  See  if  the  user  owns  the  media  (uid  matches  that  in  the  bar  header)  before  overwriting  bar-file  with  the 
C  key  word. 
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T  When  using  the  x  or  t  function  letters,  terminate  the  search  of  the  media  after  all  the  files  specified  are 
extracted  (for  x)  or  listed  (for  t). 

I  Use  the  next  argument  as  a  file  containing  a  list  of  named  files,  one  per  line,  to  be  included  in  the  bar 
archive.  The  include  file  expects  filenames  to  be  followed  by  a  semicolon  and  newline  character. 

In  the  case  where  excluded  files  (see  X  flag)  also  exist,  excluded  files  take  precedence  over  all  included 
files.  So,  if  a  file  is  specified  in  both  the  include  and  exclude  files  (or  on  the  command  line),  it  will  be 
excluded. 

OPTIONS 

-C  dir  filename 

In  a  c  (create)  or  r  (replace)  operation,  bar  performs  a  chdir  (see  csh(l))  to  that  directory  before  inter¬ 
preting  filename.  This  allows  multiple  directories  not  related  by  a  close  common  parent  to  be  archived 
using  short  relative  path  names.  For  example,  to  archive  files  from  /usr/include  and  from  /etc,  one 
might  use: 

example  %  bar  c  -C  /usr  include  -C  /etc  . 

If  you  get  a  table  of  contents  from  the  resulting  bar-file,  you  will  see  something  like: 

include/ 

include/a.out.h 

and  all  the  other  files  in  /usr/include . ,  ichown 
and  all  the  other  files  in  /etc 

Note:  the  -C  option  only  applies  to  one  following  directory  name  and  one  following  file  name. 

EXAMPLES 

Here  is  a  simple  example  using  bar  to  create  an  archive  of  your  home  directory  on  a  tape  mounted  on  drive 
/dev/rmtO: 

example  %  cd 

example  %  bar  cvf  /dev/rmtO  , 

messages 

The  c  option  means  create  the  archive;  the  v  option  makes  bar  tell  you  what  it’s  doing  as  it  works;  the  f 
option  means  that  you  are  specifically  naming  the  file  onto  which  the  archive  should  be  placed  (/dev/rmtO 
in  this  example). 

Here  is  another  example:  /dev/rmtO: 


example  %  cd 

example%  bar  cvfH  /dev/rmtO  "THIS  IS  MY  HEADER"  . 

messages 

As  in  the  first  example,  the  c  option  means  create  the  archive;  the  v  option  makes  bar  tell  you  what  it’s 
doing  as  it  works;  the  f  option  means  that  you  are  specifically  naming  the  file  onto  which  the  archive 
should  be  placed  (/dev/rmtO  in  this  example).  The  H  option  says  to  use  the  string  "THIS  IS  MY 
HEADER"  as  the  ID  field  in  the  volume  header. 

Now  you  can  read  the  table  of  contents  from  the  archive  like  this: 
exam  pie  %  bar  tvf  /dev/rmtO 

(access  user-id/group-id  size  mod.  date  filename) 

rw-r-r- 1677/40  2123  Nov  7  18:15:1985  yarchive/testc 

example% 
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You  can  extract  files  from  the  archive  like  this: 
example%  bar  xvf /dev/rmtO 

messages 

If  there  are  multiple  archive  files  on  a  tape,  each  is  separated  from  the  following  one  by  an  EOF  marker, 
bar  does  not  read  the  EOF  mark  on  the  tape  after  it  finishes  reading  an  archive  file  because  bar  looks  for  a 
special  header  to  decide  when  it  has  reached  the  end  of  the  archive.  Now  if  you  try  to  use  bar  to  read  the 
next  archive  file  from  the  tape,  bar  does  not  know  enough  to  skip  over  the  EOF  mark  and  tries  to  read  the 
EOF  mark  as  an  archive  instead.  The  result  of  this  is  an  error  message  from  bar  to  the  effect: 

bar:  blocksize=0 

This  means  that  to  read  another  archive  from  the  tape,  you  must  skip  over  the  EOF  marker  before  starting 
another  bar  command.  You  can  accomplish  this  using  the  mt  command,  as  shown  in  the  example  below. 
Assume  that  you  are  reading  from  /dev/nrmtO. 

example  %  bar  xvfp  /dev/nrmtO  read  first  archive  from  tape 
messages 

example  %  mt  fsf  1  skip  over  the  end~of-file  marker 
example%  bar  xvfp  /dev/nrmtO  read  second  archive  from  tape 
messages 

example  % 

Finally,  here  is  an  example  using  bar  to  transfer  files  across  the  Ethernet.  First,  here  is  how  to  archive  files 
from  the  local  machine  (example)  to  a  tape  on  a  remote  system  (host): 


example  %  bar  cvfb  -  20  filenames  [  rsh  host  dd  of=/dev/rmtO  obs=20b 

messages 

example  % 

In  the  example  above,  we  are  creating  a  bar-file  with  the  c  key  letter,  asking  for  verbose  output  from  bar 
with  the  V  option,  specifying  the  name  of  the  output  bar-file  using  the  f  option  (the  standard  output  is  where 
the  bar-file  appears,  as  indicated  by  the  -  sign),  and  specifying  the  blocksize  (20)  with  the  b  option.  If  you 
want  to  change  the  blocksize,  you  must  change  the  blocksize  arguments  both  on  the  bar  command  and  on 
the  dd  command. 

Now,  here  is  how  to  use  bar  to  get  files  from  a  tape  on  the  remote  system  back  to  the  local  system: 


example%  rsh  -n  host  dd  if=/dev/rmtO  bs=20b  1  bar  xvBfb  -  20  filenames 

messages 

example  % 

In  the  example  above,  we  are  extracting  from  the  bar-file  with  the  x  key  letter,  asking  for  verbose  output 
from  bar  with  the  v  option,  telling  bar  it  is  reading  from  a  pipe  with  the  B  option,  specifying  the  name  of 
the  input  bar-file  using  the  f  option  (the  standard  input  is  where  the  bar-file  appears,  as  indicated  by  the 
sign),  and  specifying  the  blocksize  (20)  with  the  b  option, 

FILES 

/dev/rmt?  half-inch  magnetic  tape  interface 

/dev/rar?  quarter-inch  magnetic  tape  interface 

/dev/rst?  SCSI  tape  interface 

/tm  p/bar + 

ENVIRONMENT 

TAPE  If  specified,  in  the  environment,  the  value  of  TAPE  indicates  the  default  tape  device. 
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NOTES 

bar  will  handle  multiple  volumes  gracefully.  If  a  tape  error  is  encountered,  bar  issues  a  message  on  the 
standard  error  requesting  a  new  volume.  The  presence  of  a  new  volume  is  confirmed  when  bar  reads  a  line 
beginning  with  Y  or  y  on  the  standard  input;  a  line  beginning  with  N  or  n  aborts  the  archive;  with  any  other 
character  bar  reissues  the  prompt. 

SEE  ALSO 

cpio(l)»  mt(l),  umask(2V),  bar(5),  tar(5),  dump(8),  restore(8) 

BUGS 

Neither  the  r  option  nor  the  u  option  can  be  used  with  quarter-inch  archive  tapes,  since  these  tape  drives 
cannot  backspace. 

There  is  no  way  to  ask  for  the  nth  occurrence  of  a  file. 

The  u  option  can  be  slow. 

There  is  no  way  selectively  to  follow  symbolic  links. 

When  extracting  tapes  created  with  the  r  or  u  options,  directory  modification  times  may  not  be  set 
correctly. 

Files  with  names  longer  than  100  characters  cannot  be  processed. 

Filename  substitution  wildcards  do  not  work  for  extracting  files  from  the  archive.  To  get  around  this,  use  a 
command  of  the  form: 

bar  xvf. . .  /dev/rstO  ‘bar  tf. . .  /dev/rstO  |  grep  ^pattern 

If  you  specify  as  the  target  file  and  the  archive  spans  volumes,  the  request  for  a  new  volume  may  get 
lost. 
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NAME 

basename,  dimame  ~  display  portions  of  pathnames  and  filenames 
SYNOPSIS 

basename  string  [  suffix  ] 
dirname  string 

AVAILABILITY 

The  dirname  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

basename  deletes  any  prefix  ending  in  /  and  the  suf/ix,  if  present  in  string.  It  directs  the  result  to  the  stan¬ 
dard  output,  and  is  normally  used  inside  substitution  marks  C  ')  within  shell  procedures. 

dirname  delivers  all  but  the  last  level  of  the  path  name  in  string. 

EXAMPLES 

This  shell  procedure  invoked  with  the  argument  /usr/src/bin/catx  compiles  the  named  file  and  moves  the 
output  to  cat  in  the  current  directory: 
cc  $1 

mv  a.out  'basename  $1  .c' 

The  following  example  will  set  the  shell  variable  NAME  to  /usr/src/cmd: 

NAME=‘dirname  /usr/src/cmd/catc‘ 

SEE  ALSO 

sh(l) 
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NAME 

be  -  arbitrary-precision  arithmetic  language 
SYNOPSIS 

be  [  -c  ]  [  -1  ]  [filename . . .] 

DESCRIPTION 

be  is  an  interactive  processor  for  a  language  which  resembles  C  but  provides  unlimited  precision  arith¬ 
metic,  be  takes  input  from  any  files  given,  then  reads  the  standard  input. 

OPTIONS 

-c  Compile  only,  be  is  actually  a  preprocessor  for  dc(l),  which  it  invokes  automatically,  unless  the 
-e  (compile  only)  option  is  present.  In  this  case  the  dc  input  is  sent  to  the  standard  output  instead. 

-I  Is  the  name  of  an  arbitrary  precision  math  library. 

USAGE 

Comments 

Enclosed  in  /  *  and  *  /. 


Names 

Simple  variables:  /,  where,  /  is  a  lower-case  letter. 

Array  elements:  l[expression]y  where,  expression  is  a  legal  be  expression. 
The  words  ibase,  obase,  and  scale. 


Other  Operands 

Arbitrarily  long  numbers  with  optional  sign  and  decimal  point. 
(expression) 
sqrt  (expression) 

length  (expression)  Number  of  significant  decimal  digits 
scale  (expression)  Number  of  digits  right  of  decimal  point 
/  (expression ,  . . .,  expression ) 


Operators 

+  -*/%"  (%  is  remainder; "  is  exponent) 

++  —  prefix  and  postfix;  apply  to  names) 

__  ^  > 


=  +=  -=  *=  /=  %= 


Statements 

expression 

{statement ;  . . . ;  statement) 

where,  statement  is  a  legal  be  statement. 

if  (expression)statement 

while  (  expression  )  statement 

for  ( expression  ;  expression  ;  expression )  statement 

null  statement 

break 

quit 

Function  Definitions 

define  /(/,...,/){ 
auto  I  i,,.,  I 
statement ; . . .  statement 
return  ( expression  ) } 
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Functions  in  —1  Math  Library 


six) 

sine 

C(x) 

cosine 

eix) 

exponential 

Kx) 

log 

a(x) 

arctangent 

j(n»x) 

Bessel  function 

All  function  arguments  are  passed  by  value. 

The  value  of  a  statement  that  is  an  expression  is  printed  unless  the  main  operator  is  an  assignment.  Either 
semicolons  or  newlines  may  separate  statements.  Assignment  to  scale  influences  the  number  of  digits  to  be 
retained  on  arithmetic  operations  in  the  manner  of  dc(l).  Assignments  to  ibase  or  obase  set  the  input  and 
output  number  radix  respectively. 

The  same  letter  may  be  used  as  an  array,  a  function,  and  a  simple  variable  simultaneously.  All  variables 
are  global  to  the  program.  ‘Auto*  variables  are  pushed  down  during  function  calls.  When  using  arrays  as 
function  arguments  or  defining  them  as  automatic  variables  empty  square  brackets  must  follow  the  array 
name. 

EXAMPLES 

Define  a  function  to  compute  an  approximate  value  of  the  exponential  function: 

scale  =  20 

define 

e(x){ 

auto  a,  b,  c,  i,  s 
a  =  1 
b  =  l 
s  =  1 

for(i=l;  1==1;  i++){ 
a  =  a*x 
b  =  b*i 
c  =  a/b 

if(c  ==  0)  return(s) 
s  =  s+c 

} 

} 

Print  approximate  values  of  the  exponential  function  of  the  first  ten  integers: 
for(i=l;  i<=10;  i++)  e(i) 

FILES 

/usr/lib/lib.b 
dc(l) 

SEE  ALSO 

dc(l) 

BUGS 

for  statement  must  have  all  three  expression's. 
quit  is  interpreted  when  read,  not  when  executed. 


mathematical  library 
desk  calculator  proper 
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NAME 

biff  give  notice  of  incoming  mail  messages 

SYNOPSIS 

biff[ylii] 

DESCRIPTION 

biff  turns  mail  notification  on  or  off  for  the  terminal  session.  With  no  arguments,  biff  displays  the  current 
notification  status  for  the  terminal. 

If  notification  is  allowed,  the  terminal  rings  the  bell  and  displays  the  header  and  the  first  few  lines  of  each 
arriving  mail  message,  biff  operates  asynchronously.  For  synchronized  notices,  use  the  MAIL  variable  of 
sh(l)  or  the  mail  variable  of  csh(l). 

A  ‘biff  y’  command  can  be  included  in  your  .login  or  .profile  file  for  execution  when  you  log  in. 

OPTIONS 

y  Allow  mail  notification  for  the  terminal, 
n  Disable  notification  for  the  terminal. 

FILES 

.login 

.profile 

SEE  ALSO 

cmdtool(l),  csh(l),  mail(l),  sh(l),  shelltool(l),  sunview(l),  comsat(8C) 

BUGS 

You  must  have  ownership  the  terminal  to  change  its  mail-notification  status  with  biff,  but  windows  running 
under  sunview(l)  are  owned  by  the  super-user.  If  you  enable  mail  notification  for  the  workstation  console 
(in  your  .login  or  .profile  file),  incoming  mail  notices  also  appear  on  console  windows  running  under  sun- 
view(l).  See  shentool(l)  or  cmdtool(l)  for  details. 
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NAME 

bin-mail,  binmail  -  an  early  program  for  processing  mail  messages 
SYNOPSIS 

/usr/bin/mail  [  -ipq  ]  [  -f filename  ]  address 
/usr/bin/mail  recipient . . . 

DESCRIPTION 

Note:  This  is  the  old  version  7  UNIX  system  mail  program.  The  default  mail  command,  /usr/ucb/mail  is 
described  in  mail(l). 

/usr/bin/mail  with  no  address  prints  a  user’s  mail,  message-by-message  in  last-in,  first-out  order, 
/usr/bin/mail  accepts  commands  from  the  standard  input  to  direct  disposition  messages. 

When  addresses  are  named,  /usr/bin/mail  takes  the  standard  input  up  to  an  EOF  (or  a  line  with  just  *,’) 
and  routes  it  through  the  mailer  daemon  to  each  recipient.  See  sendmail(8)  for  details.  The  message  is 
preceded  by  the  sender’s  name  and  a  postmark.  Lines  that  look  like  postmarks  are  prepended  with  *>’.  A 
recipient  is  a  user  name  recognized  by  login(l),  a  network  address  or  local  mail  alias,  or  a  filename  (see 
aliases(5)  for  details). 

If  there  is  any  pending  mail,  login  tells  you  there  is  mail  when  you  log  in.  It  is  also  possible  to  have  the  C 
shell,  or  the  daemon  biff  tell  you  about  mail  that  arrives  while  you  are  logged  in. 

To  forward  mail  automatically,  add  the  addresses  of  additional  recipients  to  the  .forward  file  in  your  home 
directory.  Note:  forwarding  addresses  must  be  valid,  or  the  messages  will  bounce.  You  cannot,  for 
instance,  reroute  your  mail  to  a  new  host  by  forwarding  it  to  your  new  address  if  it  is  not  yet  listed  in  the 
Network  Information  Service  (NTS)  aliases  domain. 


OPTIONS 
— i 

-P 

-q 

-f  filename 

USAGE 

1 

CTRL-D 

Icommand 


RETURN 

d 

dq 

m  [  recipient  ] 

n 

P 

q 


Ignore  interrupts. 

Print  messages  without  prompting  for  commands.  Exit  immediately  upon  receiving  an 
interrupt. 

Quit  immediately  upon  interrupt. 

Use  filename  as  if  it  were  the  mail  file. 

Print  a  command  summary. 

Put  unexamined  mail  back  in  the  mail  file  and  quit. 

Escape  to  the  shell  to  do  command. 

Go  back  to  previous  message. 

Go  on  to  next  message. 

Go  on  to  next  message. 

Delete  message  and  go  on  to  the  next. 

Delete  message  and  quit. 

. . .  Mail  the  message  to  the  named  recipients  (yourself  is  default). 

Go  on  to  next  message. 

Print  message  (again). 

Same  as  EOT . 
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s  { filename^ Save  the  message  in  the  namod  filenames  (‘mbox’  default).  If  saved  successfully, 
remove  it  from  the  list  and  go  on  to  the  next  message. 

w  [filename  ] ...  Save  the  message,  without  a  header,  in  the  named  filenames  (‘mbox’  default).  If  saved 
successfully,  remove  it  from  the  list  and  go  on  to  the  next  message. 

X  Exit  without  changing  the  mail  file. 

FILES 

/etc/passwd  to  identify  sender  and  locate  address 

/var/spool/mail/*  incoming  mail  for  user  + 

/usr/ucb/mail  routes  input  through  daemon  to  recipients 

mbox  saved  mail 

/tmp/ma*  temp  file 

/var/spool/mail/*  .lock  lock  for  mail  directory 
deaddetter  unmailable  text  is  saved  here 

$HOME/.forward  list  of  forwarding  recipients 

SEE  ALSO 

biff(l),  csh(l),  des(l),  login(l),  mail(l),  uucp(lC),  uux(lC),  write(l),  xsend(l),  crypt(3),  aliases(5), 
sendmail(8) 

BUGS 

Race  conditions  sometimes  result  in  a  failure  to  remove  a  lock  file. 

The  super-user  can  read  your  mail,  unless  it  is  encrypted  by  des(l),  xsend(l),  or  crypt(3).  Even  if  you 
encrypt  it,  the  super-user  can  delete  it. 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed. 
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NAME 

cal  -  display  a  calendar 

SYNOPSIS 

cal  [  [  month  ]  year  ] 

DESCRIPTION 

cal  displays  a  calendar  for  the  specified  year.  If  a  month  is  also  specified,  a  calendar  for  that  month  only  is 
displayed.  If  neither  is  specified,  a  calendar  for  the  present  month  is  printed. 

year  can  be  between  1  and  9999.  Be  aware  that  ‘cal  78’  refers  to  the  early  Christian  era,  not  the  20th  cen¬ 
tury.  Also,  the  year  is  always  considered  to  start  in  January,  even  though  this  is  historically  naive. 

month  is  a  number  between  1  and  12. 

The  calendar  produced  is  that  for  England  and  her  colonies. 

Try  September  1752. 
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NAME 

calendar  -  a  simple  reminder  service 

SYNOPSIS 

calendar  [  -  ] 

DESCRIPTION 

calendar  consults  the  file  calendar  in  the  current  directory  and  displays  lines  that  contain  today’s  or 
tomorrow’s  date  anywhere  in  the  line.  Most  reasonable  month-day  dies  —  such  as  ‘Dec.  7,’  ‘december 
7,’  and  ‘12/7*  —  are  recognized,  but  ‘7  December’  or  ‘7/12’  are  not.  If  you  give  the  month  as  ‘♦’  with  a 
date  —  for  example,  “*  1”  —  that  day  in  any  month  will  do.  On  weekends  “tomorrow”  extends  through 
Monday. 

When  the  optional  ‘-’  argument  is  present,  calendar  does  its  job  for  every  user  who  has  a  file  calendar  in 
his  login  directory  and  sends  him  any  positive  results  by  niail(l).  Normally  this  is  done  daily  in  the  wee 
hours  under  control  of  cron(8). 

The  file  calendar  is  first  run  through  the  C  preprocessor,  cpp(l),  to  include  any  other  calendar  files 
specified  with  the  usual  #include  syntax.  Included  calendars  are  usually  shared  by  all  users,  and  main¬ 
tained  by  the  system  administrator. 

FILES 

“/calendar 

/usr/lib/calendar  to  figure  out  today’s  and  tomoirow’s  dates 

/etc/passwd 

/tmp/cal* 

/lib/cpp 

SEE  ALSO 

at(l),  cpp(l),  grep(lV),  mail(l),  aliases(5),  cron(8) 

NOTES 

The  ‘“*  argument  works  only  on  calendar  files  that  are  local  to  the  machine;  calendar  is  intended  not  to 
work  on  calendar  files  that  are  mounted  remotely  with  NFS.  Thus,  ‘calendar  -’  should  be  run  only  on 
diskful  machines  where  home  directories  exist;  running  it  on  a  diskless  client  has  no  effect. 

calendar  is  no  longer  in  the  default  root  crontab.  Because  of  the  network  burden  ‘calendar  -’  can  induce, 
it  is  inadvisable  in  an  environment  running  ypbind  (see  ypserv(8))  with  a  large  passwd.byname  map. 
However,  if  the  usefulness  of  calendar  outweighs  the  network  impact,  the  super-user  may  run  ‘crontab 
-e’  to  edit  the  root  crontab.  Otherwise,  individual  users  may  wish  to  use  ‘crontab  -e’  to  edit  their  own 
crontabs  to  have  cron  invoke  calendar  without  the  argument,  piping  ou^ut  to  mail  addressed  to  them¬ 
selves. 

BUGS 

calendar ’s  extended  idea  of  “tomorrow”  does  not  account  for  holidays. 

Problems  may  occur  when  there  is  no  /etc/passwd  file  on  the  local  host. 

The  calendar  mail  will  be  sent  to  the  user  at  the  machine  on  which  ‘calendar  -’  is  run.  If  the  system 
administrator  wants  the  mail  to  be  sent  to  another  machine,  mail  aliases  should  be  set  up  accordingly. 
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NAME 

cat  -  concatenate  and  display 
SYNOPSIS 

cat  [  -  ]  [  -benstuv  ]  [filename , . .  ] 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/cat [ - ]  [ -estuv ]  [filename.. .  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

cat  reads  each  filename  in  sequence  and  displays  it  on  the  standard  output.  Thus: 
example%  cat  goodies 

displays  the  contents  of  goodies  on  the  standard  output,  and 
example  %  cat  goodiesl  goodies2  >  goodies3 
concatenates  the  first  two  files  and  places  the  result  on  the  third. 

If  no  filename  argument  is  given,  or  if  the  argument  is  given,  cat  reads  from  the  standard  input.  If  the 
standard  input  is  a  terminal,  input  is  terminated  by  an  EOF  condition. 

OPTIONS 

-b  Number  the  lines,  as  -n,  but  omit  the  line  numbers  from  blank  lines. 

-e  Display  non-printing  characters,  as  -v,  and  in  addition  display  a  $  character  at  the  end  of  each 

line. 

-n  Precede  each  line  output  with  its  line  number. 

~s  Substitute  a  single  blank  line  for  multiple  adjacent  blank  lines. 

-t  Display  non-printing  characters,  as  -v,  and  in  addition  display  TAB  characters  as "  I  (CTRL-I). 

-u  Unbuffered.  If  -u  is  not  used,  output  is  buffered  in  blocks,  or  line-buffered  if  standard  output  is  a 

terminal. 

-V  Display  non-printing  characters  (with  the  exception  of  TAB  and  NEWLINE  characters)  so  that  they 
are  visible.  Control  characters  print  like  "X  for  CTRL-X;  the  DEL  character  (octal  0177)  print  as 
Non-ASCn  characters  (with  the  high  bit  set)  are  displayed  as  M-x  where  M-  stands  for 
*meta’  and  x  is  the  character  specified  by  the  seven  low  order  bits. 

SYSTEM  V  OPTIONS 

-e  If  the  ~v  option  is  specified,  display  a  $  character  at  the  end  of  each  line. 

-s  Suppress  messages  about  files  which  cannot  be  opened. 

-t  If  the  -V  option  is  specified,  display  TAB  characters  as  "I  (CTRL-I)  and  FORMFEED  characters  as 
"L(CTRL-L). 

“V  Display  non-printing  character  (with  the  exception  of  TAB,  NEWLINE,  and  FORMFEED  charac¬ 
ters)  so  that  they  are  visible. 

ENVIRONMENT 

The  environment  variables  LC  CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  cat.  On  entry  to  cat,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  “C”  locale. 
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SEE  ALSO 

cp(l),  ex(l),  more(l),  pg(lV),  pr(lV)»  tail(l) 

NOTES 

Beware  of  ‘cat  a  b  >  a’  and  ‘cat  a  b  >  b%  which  destroy  the  input  files  before  reading  them. 
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NAME 

cb  -  a  simple  C  program  beautifier 
SYNOPSIS 

cb  [  -js  ]  [  -1  leng  ]  [filename. . .  ] 

DESCRIPTION 

cb  reads  C  programs  either  from  its  arguments  or  from  the  standard  input  and  writes  them  on  the  standard 
output  with  spacing  and  indentation  that  displays  the  structure  of  the  code. 

indent(l)  is  preferred. 

OPTIONS 

With  no  options,  cb  preserves  all  user  NEWLINE  characters. 

-j  Join,  Split  lines  are  put  back  together. 

-s  Standard  C  style.  Formats  the  code  to  the  style  of  Kemighan  and  Ritchie  in  The  C  Programming 
Language. 

-1  leng  Split  lines  longer  than  leng. 

SEE  ALSO 

indent(l) 

B.W.  Kemighan  and  D.M.  Ritchie,  The  C  Programming  Language,  Prentice-Hall,  1978 

BUGS 

Punctuation  hidden  in  preprocessor  statements  can  cause  indentation  errors. 
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NAME 

cc  -  C  compiler 
SYNOPSIS 

cc  [  ~a  ]  [  -align  J?lock  ]  [  -Bbinding  ]  [  -c  ]  [  -C  ]  [  -dalign  ]  [  -dryrun  ]  [  -Dname  [=def]  ]  [  ~E  ] 
[float_option  ]  [  -fsingle  ]  [  ~g  ]  [  -go  ]  [  -help  ]  [  -{pathname  ]  [  -J  ]  [  -Ldirectory  ]  [  -M  ] 

[  -misalign  ]  [  -o  outputfile  ]  [  ~0[level]  ]  [  -p  ]  [  -P  ]  [  -pg  ]  [  -pic  ]  [  -PIC  ]  [  -pipe  ] 

[  -Qoption  prog  opt  ]  [  -Qpath  pathname  ]  [  -Qproduce  sourcetype  ]  [  -R  ]  [  -S  ]  [  -sb  ] 

[  -target  target_arch  ]  [  -iemp=directory  ]  [  -time  ]  [  -Vname  ]  [  -w  ]  sourcefile  . . . 

[  -Mibrary  ] 

SYSTEM  V  SYNOPSIS 

/usr/5bin/cc  arguments 

/usr/xpg2bin/cc  arguments 

Note:  arguments  to  /usr/5bin/cc  and  /usr/xpg2bin/cc  are  identical  to  those  listed  above. 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

cc  is  the  C  compiler.  It  translates  programs  written  in  the  C  programming  language  into  executable  load 
modules,  or  into  relocatable  binary  programs  for  subsequent  loading  with  the  ld(l)  link  editor. 

In  addition  to  the  many  options,  cc  accepts  several  types  of  filename  arguments.  For  instance,  files  with 
names  ending  in  ,c  are  taken  to  be  C  source  programs.  They  are  compiled,  and  each  resulting  object  pro¬ 
gram  is  placed  in  the  current  directory.  The  object  file  is  named  after  its  source  file  —  the  suffix  .o  replac¬ 
ing  ,c  in  the  name  of  the  object.  In  the  same  way,  files  whose  names  end  with  .s  are  taken  to  be  assembly 
source  programs.  They  are  assembled,  and  produce  .0  files.  Filenames  ending  in  .il  are  taken  to  be  inline 
expansion  code  template  files;  these  are  used  to  expand  calls  to  selected  routines  in-line  when  code  optimi¬ 
zation  is  enabled.  See  FILES,  below  for  a  complete  list  of  compiler-related  filename  suffixes. 

Other  arguments  refer  to  assembler  or  loader  options,  object  programs,  or  object  libraries.  Unless  -c,  -S, 
-E  -P  or  -Qproduce  is  specified,  these  programs  and  libraries,  together  with  the  results  of  any  specified 
compilations  or  assemblies,  are  loaded  (in  the  order  given)  to  produce  an  output  file  named  a.out.  You  can 
specify  a  name  for  the  executable  by  using  the  -o  option. 

If  a  single  file  is  compiled  and  loaded  all  at  once,  the  intermediate  file  is  deleted. 

/usr/xpg2bin/cc  is  a  shell  script  that  should  be  used  to  compile  X/Open  compliant  applications. 
/usr/Sbin/cc  and  /usr/xpg2bin/cc  accept  the  same  arguments  and  options  as  cc.  /usr/xpg2bin/cc  searches 
/usr/xpg2include  for  ^include  files  before  /usr/include,  and  specifies  /usr/xpg21ib/libxpg.a  as  an  addi¬ 
tional  static  library  of  object-library  routines. 

OPTIONS 

When  debugging  or  profiling  objects  are  compiled  using  the  -g  or  -pg  options,  respectively,  the  Id  com¬ 
mand  for  linking  them  should  also  contain  the  appropriate  option. 

See  ld(l)  for  link-time  options. 


-a 


-align  Jtlock 
-Bbinding 


Insert  code  to  count  how  many  times  each  basic  block  is  executed.  Invokes  a  run-time 
recording  mechanism  that  creates  a  .d  file  for  every  .c  file  (at  normal  termination).  The 
.d  file  accumulates  execution  data  for  the  corresponding  source  file.  The  tcov(l)  utility 
can  then  be  run  on  the  source  file  to  generate  statistics  about  the  program.  Since  this 
option  entails  some  optimization,  it  is  incompatible  with  -g. 

Force  the  global  uninitialized  data  symbol  block  to  be  page-aligned  by  increasing  its  size 
to  a  whole  number  of  pages,  and  placing  its  first  byte  at  the  beginning  of  a  page. 

Specify  whether  bindings  of  libraries  for  linking  are  static  or  dynamic,  indicating 
whether  libraries  are  non-shared  or  shared,  respectively. 
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-c 

-C 

-dalign 

-dryrun 

-Dname[=de!f\ 

-E 

float_option 


-fsingle 

-go 

-help 


Suppress  linking  with  ld(l)  and  produce  a  .o  file  for  each  source  file.  A  single  object  file 
can  be  nanied  explicitly  using  the  -o  option. 

Prevent  the  C  preprocessor,  cpp(l),  from  removing  comments. 

(Sun~4  systems  only.) 

Generate  double  load/store  instructions  whenever  possible  for  improved  performance. 
Assumes  that  all  double  typed  data  are  double  aligned,  and  should  not  be  used  when 
correct  alignment  is  not  assured. 

Show  but  do  not  execute  the  commands  constructed  by  the  compilation  driver. 

Define  a  symbol  name  to  the  C  preprocessor  (cpp(l)).  Equivalent  to  a  #define  directive 
in  the  source.  If  no  def  is  given,  name  is  defined  as  ‘1’. 

Run  the  source  file  through  cpp(l),  the  C  preprocessor,  only.  Sends  the  output  to  the 
standard  output,  or  to  a  file  named  with  the  -o  option.  Inclu(tes  the  cpp  line  numbering 
information.  (See  also,  the  -P  option.) 

Floating-point  code  generation  option.  Can  be  one  of: 

-f68881  Generate  in-line  code  for  Motorola  MC6888 1  flowing-point  processor  (sup¬ 
ported  only  on  Sun-3  systems). 

-ffpa  Generate  in-line  code  for  Sun  Floating  Point  Accelerator  (supported  only  on 
Sun-3  systems). 

-fsky  Generate  in-line  code  for  Sky  floating-point  processor  (supported  only  on 
Sun-2  systems). 

-fsoft  Generate  software  floating-point  calls.  Supported  only  on  Sun-2  and  Sun-3 
systems,  for  which  it  is  the  default. 

-fstore  Insure  that  expressions  allocated  to  extended  precision  registers  are  rounded 
to  storage  precision  whenever  an  assignment  occurs  in  the  source  code. 
Only  has  effect  when  -f68881  is  specified  (Sun-3  systems  only). 

-fswitch  Run-time-switched  floating-point  calls.  The  compiled  object  code  is  linked 
at  runtime  to  routines  that  support  one  of  the  above  types  of  floating  point 
code.  This  was  the  default  in  previous  releases.  Only  for  use  with  programs 
that  are  floating-point  intensive,  and  must  be  portable  to  machines  with  vari¬ 
ous  floating-point  hardware  options  (supported  only  on  Sun-2  and  Sun-3  sys¬ 
tems). 

(Sun-2,  Sun-3  and  Sun-4  systems) 

Use  single-precision  arithmetic  in  computations  involving  only  float  expressions.  Do  not 
convert  everything  to  double,  which  is  the  default.  Note:  floating-point  parameters  are 
still  converted  to  double  precision,  and  functions  returning  values  still  return  double¬ 
precision  values. 

Although  not  standard  C,  certain  programs  run  much  faster  using  this  option.  Be  aware 
that  some  significance  can  be  lost  due  to  lower-precision  intermediate  values. 

Produce  additional  symbol  table  information  for  dbx(l)  and  dbxtool(l)  and  pass  -Ig 
option  to  ld(l)  (so  as  to  include  the  g  library,  that  is:  /usr/lib/libg.a).  When  this  option  is 
given,  the  -O  and  -R  options  are  suppressed. 

Produce  additional  symbol  table  information  for  adb(l).  When  this  option  is  given,  the 
-O  and  -R  options  are  suppressed. 

Display  helpful  information  about  cc. 
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-Ipathname 


-J 


—[library 


-hcUrectory 

-M 


-misalign 
-o  outputfile 


-OUevel] 


“P 

-P 

-Pg 


-pic 


-PIC 

-pipe 


Add  pathname  to  the  list  of  directories  in  which  to  search  for  #include  files  with  relative 
filenames  (not  beginning  with  slash  The  preprocessor  first  searches  for  #include 
files  in  the  directory  containing  sourcefde,  then  in  directories  named  with  -I  options  (if 
any),  and  finally,  in  /usr/include. 

Generate  32-bit  offsets  in  switch  statement  labels  (supported  only  on  Sun-2  and  Sun-3 
systems). 

Link  with  object  library  library  (for  ld(l)).  This  option  must  follow  the  sourcefile  argu¬ 
ments. 

Add  directory  to  the  list  of  directories  containing  object-library  routines  (for  linking 
using  ld(l). 

Run  only  the  macro  preprocessor  on  the  named  C  programs,  requesting  that  it  generate 
makefile  dependencies  and  send  the  result  to  the  standard  output  (see  make(l)  for  details 
about  makefiles  and  dependencies). 

Generate  code  to  allow  loading  and  storage  of  misaligned  data  (Sun-4  systems  only). 

Name  the  output  file  outputfile.  outputfile  must  have  the  appropriate  suffix  for  the  type  of 
file  to  be  produced  by  the  compilation  (see  FILES,  below),  outputfile  cannot  be  the  same 
as  sourcefile  (the  compiler  will  not  overwrite  the  source  file). 

Optimize  the  object  code.  Ignored  when  either  -g,  -go,  or  -a  is  used.  -O  with  the  level 
omitted  is  equivalent  to  -02.  On  Sun386i  systems,  any  level  supplied  is  treated  as  level 
1.  level  is  one  of: 

1  Do  postpass  assembly-level  optimization  only. 

2  Do  global  optimization  prior  to  code  generation,  including  loop  optimi¬ 
zations,  common  subexpression  elimination,  copy  propagation,  and 
automatic  register  allocation.  -02  does  not  optimize  references  to  or 
definitions  of  external  or  indirect  variables. 

3  Same  as  -02,  but  optimize  uses  and  definitions  of  external  variables. 
-03  does  not  trace  the  effects  of  pointer  assignments.  Neither  -03 
nor  -04  should  be  used  when  compiling  either  device  drivers,  or  pro¬ 
grams  that  modify  external  variables  from  within  signal  handlers. 

4  Same  as  -03,  but  trace  the  effects  of  pointer  assignments. 

Prepare  the  object  code  to  collect  data  for  profiling  with  prof(l).  Invokes  a  run-dme 
recording  mechanism  that  produces  a  mon.out  file  (at  normal  terminadon). 

Run  the  source  file  through  cpp(l),  the  C  preprocessor,  only.  Puts  the  output  in  a  file 
with  a  .i  suffix.  Does  not  include  cpp-type  line  number  informadon  in  the  output. 

Prepare  the  object  code  to  collect  data  for  profiling  with  gprof(l).  Invokes  a  run-dme 
recording  mechanism  that  produces  a  gmon.out  file  (at  normal  termination). 

Produce  position-independent  code.  Each  reference  to  a  global  datum  is  generated  as  a 
dereference  of  a  pointer  in  the  global  offset  table.  Each  function  call  is  generated  in  pc- 
relative  addressing  mode  through  a  procedure  linkage  table.  The  size  of  the  global  offset 
table  is  limited  to  64K  on  MC68000-family  processors,  or  to  8K  on  SPARC  processors. 

Like  -pic,  but  allows  the  global  offset  table  to  span  the  range  of  32-bit  addresses  in  those 
rare  cases  where  there  are  too  many  global  data  objects  for  -pic. 

Use  pipes,  rather  than  intermediate  files,  between  cpp(l)  and  ccom  compilation  stages. 
Very  cpu-intensive. 
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-Qoption  prog  opt 

Pass  the  option  opt  to  the  program  prog.  The  option  must  be  appropriate  to  that  program 
and  may  begin  with  a  minus  sign,  prog  can  be  one  of;  as,  cpp,  inline,  or  Id. 

-Qpath  pathname 

Insert  directory  pathname  into  the  compilation  search  path,  pathname  will  be  searched 
for  alternate  compilation  programs,  such  as  cpp(l),  and  ld(l).  This  path  will  also  be 
searched  first  for  certain  relocatable  object  files  that  are  implicitly  referenced  by  the  com¬ 
piler  driver,  for  example  ♦crt*.o  and  bb  Jink.o. 

-Qproduce  sourcetype 

Produce  source  code  of  the  type  sourcetype.  sourcetype  can  be  one  of: 

.c  C  source  (from  bb__count). 

.i  Preprocessed  C  source  from  cpp(l). 

.0  Object  file  from  as(l). 

^  Assembler  source  (from  inline,  or  c2). 

-R  Merge  data  segment  with  text  segment  for  as(l).  Data  initialized  in  the  object  file  pro¬ 

duced  fay  this  compilation  is  read-only,  and  (unless  linked  with  Id  -N)  is  shared  between 
processes.  Ignored  when  either  -g  or  -go  is  used. 

-S  Do  not  assemble  the  program  but  produce  an  assembly  source  file. 

-sb  Generate  extra  symbol  table  information  for  the  Sun  Source  Code  Browser.  This  is  an 

unbundled  product  that  will  be  released  based  on  4.1. 


target  target jirch 

Compile  object  files  for  the  specified  processor  architecture.  Unless  used  in  conjunction 
with  one  of  the  Sun  Cross-Compilers,  correct  programs  can  be  generated  only  for  the 
architecture  of  the  host  on  which  the  compilation  is  performed,  target  arch  can  be  one 


of: 

sun2 

Produce  object  files  for  a  Sun-2  system. 

sun3 

Produce  object  files  for  a  Sun-3  system. 

~temp=directory 

sun4 

Produce  object  files  for  a  Sun-4  system. 

Set  directory  for  temporary  files  to  be  directory, 

-time  Report  execution  times  for  the  various  compilation  passes. 

-liname  Remove  any  initial  definition  of  the  cpp(l)  symbol  name .  Inverse  of  the  -D  option, 

-w  Do  not  print  warnings. 


ENVIRONMENT 


FILES 


FLOAT_OPTION 

(Sun-2,  Sun-3,  Sun-4  systems  only.)  When  no  floating-point  option  is  specified, 
the  compiler  uses  the  value  of  this  environment  variable  (if  set).  Recognized 
values  are:  f68881,  ITpa,  fsky,  fswitch  and  fsoft. 

a.out 

executable  output  file 

file. a 

library  of  object  files 

file.c 

C  source  file 

fileA 

tcov(l)  test  coverage  input  file  (Sun-2,  Sun-3,  Sun-4  systems  only) 

fileA 

C  source  file  after  preprocessing  with  cpp(l) 

fileAl 

inline  expansion  file 

file.o 

object  file 

files 

assembler  source  file 

file.S 

assembler  source  for  cpp(l) 

fileAcov 

output  from  tcov(l)  (Sun-2,  Sun-3,  Sun-4  systems  only) 

/usr/lib/c2 

object  code  optimizer 
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/usr/lib/ccom 

/usr/lib/compile 

/usr/lib/cpp 

/usr/lib/crtO.o 

/usr/lib/Fcrtl.o 

/usr/lib/gcrtO.o 

/usr/Hb/libc^ 

/usr/lib/mcrtO.o 

/usr/lib/Mcrtl.o 

/lib/optim 

/lib/Scrtl.o 

/usr/Iib/Wcrtl.o 

/usr/include 

/usr/lib/bb_link.o 

/usr/lib/cg 

/usr/lib/libc_p.a 

/usr/lib/inline 

/usr/lib/iropt 

/usr/lib/libm^ 

/usr/51ib/libc.a 

/usr/5lib/libcj).a 

/tmp/* 

/usr/xpg2include 

/usr/xpg21ib/libxpg.a 

/usr/xpg21ib/libxpg_p^ 


compiler 

compiler  command-line  processing  driver 
macro  preprocessor 
runtime  startup  code 

startup  code  for  -fsoft  option  (Sun-2»  Sun-3,  Sun-4  systems  only) 

startup  for  profiling  with  gprof(l) 

standard  library,  see  intro(3) 

startup  for  profiling  with  prof(l)  intro(3) 

startup  code  for  -f68881  option  (for  Sun-3  systems) 

Sun386i  code  optimizer 

startup  code  for  -fsky  option  (for  Sun-2  systems) 
startup  code  for  — ffpa  option  (for  Sun-3  systems) 
standard  directory  for  #include  files 
basic  block  counting  routine 
code  generator  used  with  /usr/lib/iropt 
profiling  library,  see  gprof(l)  or  prof(l) 
inline  expander  of  library  calls 
intermediate  representation  optimizer 
math  library 

System  V  standard  compatibility  library,  see  intro(3) 

System  V  profiling  library,  see  gprof(l)  or  prof(l) 
compiler  temporary  files 
directory  for  X/Open  #mclude  files 
X/Open  XPG2  compatibility  library 


Profiled  version  of  X/Open  XPG2  compatibility  library 
mon.out  file  produced  for  analysis  by  prof(l) 

gmon.out  file  produced  for  analysis  by  gprof(l) 

*cb  subdirectory  that  holds  the  information  generated  by  the  -cb  option 


SEE  ALSO 

adb(l),  ar(lV),  as(l),  cflow(lV),  cpp(l),  ctags(l),  cxref(lV),  dbx(l),  dbxtool(l),  gprof(l),  inline(l), 
ld(l),  lint(lV),  m4(lV),  make(l),  prof(l),  tcov(l),  intro(3),  monitor(3) 


Numerical  Computation  Guide 
Programming  Utilities  and  Libraries 

B.  W.  Kemighan  and  D.  M.  Ritchie,  The  C  Programming  Language,  Prentice-Hall,  1978 


DIAGNOSTICS 

The  diagnostics  produced  by  the  C  compiler  are  intended  to  be  self-explanatory.  Occasional  obscure  mes¬ 
sages  may  be  produced  by  the  preprocessor,  assembler,  or  loader. 

NOTES 

While  the  compiler  allows  8-bit  strings  and  comments,  8-bits  are  not  allowed  anywhere  else.  The  cc  com¬ 
mand  does  not  generate  or  support  8-bit  symbol  names  because,  until  ANSI  C,  non-ASCH  support  was  not 
expected.  The  ANSI  C  specification  now  suggests  that  string  literals  and  comments  can  contain  any  charac¬ 
ters  from  any  character  code  set. 

The  following  commands  are  affected  by  this  lack  of  support  for  8-bit  characters:  cflow(lV),  cpp(l), 
ctags(l),  cxref(lV),  dbx(l),  lint(lV),  m4(lV),  and  yacc(l). 

BUGS 

The  program  context  given  in  syntax  error  messages  is  taken  from  the  input  text  after  the  C  preprocessor 
has  performed  substitutions.  Therefore,  error  messages  involving  syntax  errors  in  or  near  macro  references 
or  manifest  constants  may  be  misleading. 
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Compiling  with  optimization  level  2  or  greater  may  produce  incorrect  object  code  if  tail-recursion  elimina¬ 
tion  is  applied  to  functions  called  with  fewer  actual  parameters  (arguments)  than  the  number  of  formal 
parameters  in  the  function’s  definition.  Such  parameter-count  mismatches  can  be  detected  using  lint(l  V). 
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NAME 

cd  -  change  working  directory 

SYNOPSIS 

cd  [  directory  ] 

DESCRIPTION 

directory  becomes  the  new  working  directory.  The  process  must  have  execute  (search)  permission  in 
directory.  If  cd  is  used  without  arguments,  it  returns  you  to  your  login  directory.  In  csh(l)  you  may 
specify  a  list  of  directories  in  which  directory  is  to  be  sought  as  a  subdirectory  if  it  is  not  a  subdirectory  of 
the  current  directory;  see  the  description  of  the  cdpath  variable  in  csh(l). 

SEE  ALSO 

csh(l),  pwd(l),  sh(l) 
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NAME 

cflow  -  generate  a  flow  graph  for  a  C  program 
SYNOPSIS 

cflow  [-r]  [~ix]  [-i_]  [-dnum]  filenames 

SYSTEM  V  SYNOPSIS 

cflow  [-r]  [-ix]  [  -i_  ]  [  -dnum  ]  filenames 
AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

cflow  analyzes  a  collection  of  C,  yacc,  lex,  assembler,  and  object  files  and  attempts  to  build  a  graph  chart¬ 
ing  the  external  references.  Files  suffixed  in  .y  and  .1  are  run  through  yacc  and  lex,  respectively;  the  out¬ 
put  of  yacc  and  lex  for  those  files,  and  files  suffixed  in  ,  c,  are  first  run  through  the  C  preprocessor  and  then 
run  through  the  first  pass  of  liiit(lV).  (The  -I,  — D,  and  -U  options  of  the  C  preprocessor  are  also  under¬ 
stood.)  Files  suffixed  in  .  i  are  passed  direcdy  to  the  first  pass  of  lint.  Files  suffixed  with  .  s  are  assembled. 
Information  is  extracted  from  the  symbol  tables  of  the  output  of  the  assembler  and  from  files  suffixed  with 
.0.  The  output  of  all  this  non-trivial  processing  is  collected  and  turned  into  a  graph  of  external  references 
which  is  displayed  upon  the  standard  output. 

Each  line  of  output  begins  with  a  reference  (that  is,  line)  number,  followed  by  a  suitable  number  of  tabs 
indicating  the  level.  Then  the  name  of  the  global  (normally  only  a  function  not  defined  as  an  external  or 
beginning  with  an  underscore;  see  below  for  the  -i  inclusion  option)  a  colon  and  its  definition.  For  infor¬ 
mation  extracted  from  C  source,  the  definition  consists  of  an  abstract  type  declaration  (for  example,  char 
*),  and,  delimited  by  angle  brackets,  the  name  of  the  source  file  and  the  line  number  where  the  definition 
was  found.  Definitions  extracted  from  object  files  indicate  the  file  name  and  location  counter  under  which 
the  symbol  appeared  (for  example,  text).  Leading  underscores  in  C-style  external  names  are  deleted. 

Once  a  definition  of  a  name  has  been  printed,  subsequent  references  to  that  name  contain  only  the  reference 
number  of  the  line  where  the  definition  may  be  found.  For  undefined  references,  only  <>  is  printed. 

SYSTEM  V  DESCRIPTION 

The  System  V  version  of  cflow  in  /usr/Sbin/cflow  makes  the  C  preprocessor,  cpp(l)  search  in 
/usr/5include  for  include  files  before  it  searches  in  /usr/include. 

OPTIONS 

The  following  options  are  interpreted  by  cflow  : 

-r  Reverse  the  “caller: callee’'  relationship  producing  an  inverted  listing  showing  the  callers  of  each 
function.  The  listing  is  also  sorted  in  lexicographical  order  by  callee. 

-ix  Include  external  and  static  data  symbols.  The  default  is  to  include  only  functions  in  the  flowgraph. 

-i_  Include  names  that  begin  with  an  underscore.  The  default  is  to  exclude  these  functions  (and  data  if 

-ix  is  used). 

-dnum  The  num  decimal  integer  indicates  the  depth  at  which  the  flowgraph  is  cut  off.  By  default  this  is  a 
very  large  number.  Attempts  to  set  the  cutoff  depth  to  a  nonpositive  integer  will  be  met  with  con¬ 
tempt. 
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EXAMPLES 

As  an  example,  given  the  following  in 


int  i; 
mainO 
{ 

f(); 

g(); 

f(); 

} 

f() 

{ 

i  =  h(); 

} 


the  command: 


'w' 


cfiow  -ix  file.c 
produces  the  output 

1  main:  int()»  <file.c  4> 

2  f:  into,  <file.c  11> 

3  h:  <> 

4  i:  int,  <file.c  1> 

5  g:  <> 

When  the  nesting  level  becomes  too  deep,  the  -e  option  of  pr(lV)  can  be  used  to  compress  the 
tab  expansion  to  something  less  than  eight  spaces. 

SEE  ALSO 

as(l),  cc(lV),  cpp(l),  lex(l),  Iint(lV),  nm(l),  pr(lV),  yacc(l) 

DIAGNOSTICS 

Complains  about  bad  options.  Complains  about  multiple  definitions  and  only  believes  the  first.  Other  mes¬ 
sages  may  come  from  the  various  programs  used,  such  as  the  C  preprocessor. 

NOTES 

While  the  compiler  allows  8-bit  strings  and  comments,  8-bits  are  not  allowed  anywhere  else.  See  cc(lV) 
for  an  explanation  about  why  cc  is  not  8-bit  clean. 

BUGS 

Files  produced  by  lex  and  yacc  cause  the  reordering  of  line  number  declarations  which  can  confuse  cflow. 
To  get  proper  results,  feed  cflow  the  yacc  or  lex  input. 
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NAME 

checknr  -  check  nroff  and  troff  input  files;  report  possible  errors 
SYNOPSIS 

checknr  [~fs]  [ -a. .xn  .yn][-c  .xl  ,x2  .xB  ...  .  xn][  filename  ...  ] 
AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

checknr  checks  a  list  of  nrolT(l)  or  troff(l)  input  files  for  certain  kinds  of  errors  involving  mismatched 
opening  and  closing  delimiters  and  unknown  commands.  If  no  files  are  specified,  checknr  checks  the  stan¬ 
dard  input.  Delimiters  checked  are: 

•  Font  changes  using  \fjc . , .  \fP. 

•  Size  changes  using  W . . .  \s0. 

•  Macros  that  come  in  open  . . .  close  forms,  for  example,  the  .TS  and  .TE  macros  which  must 
always  come  in  pairs. 

checknr  knows  about  the  ms(7)  and  me(7)  macro  packages. 

checknr  is  intended  to  be  used  on  documents  that  are  prepared  with  checknr  in  mind.  It  expects  a  certain 
document  writing  style  for  \f  and  \s  commands,  in  that  each  \fx  must  be  terminated  with  \fP  and  each  \sjc 
must  be  terminated  with  \s0.  While  it  will  work  to  direcdy  go  into  the  next  font  or  explicitly  specify  the 
original  font  or  point  size,  and  many  existing  documents  actually  do  this,  such  a  practice  will  produce  com¬ 
plaints  from  checknr.  Since  it  is  probably  better  to  use  the  \fP  and  \s0  forms  anyway,  you  should  think  of 
this  as  a  contribution  to  your  document  preparation  style, 

OPTIONS 

-f  Ignore  \f  font  changes. 

-s  Ignore  \s  size  changes. 

-a  jcl  ,yl... 

Add  pairs  of  macros  to  the  list.  The  pairs  of  macros  are  assumed  to  be  those  (such  as  .DS  and  .DE) 
that  should  be  checked  for  balance.  The  -a  option  must  be  followed  by  groups  of  six  characters, 
each  group  defining  a  pair  of  macros.  The  six  characters  are  a  period,  the  first  macro  name, 
another  period,  and  the  second  macro  name.  For  example,  to  define  a  pair  .BS  and  .ES,  use 
‘-a,BS.ES’ 

-c  jcl ... 

Define  commands  which  checknr  would  otherwise  complain  about  as  undefined. 

SEE  ALSO 

eqn(l),  nroff(l),  troff(l),  me(7),  ms(7) 

BUGS 

There  is  no  way  to  define  a  one-character  macro  name  using  the  -a  option. 
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NAME 

chgrp  -  change  the  group  ownership  of  a  file 
SYNOPSIS 

chgrp  [  -f  ]  [  -R  ]  groupfilename.. . 

DESCRIPTION 

chgrp  changes  the  group  ID  (GID)  of  the  filenames  given  as  arguments  to  group.  The  group  may  be  either 
a  decimal  GID  or  a  group  name  found  in  the  GID  file,  /etc/group. 

You  must  belong  to  the  specified  group  and  be  the  owner  of  the  file,  or  be  the  super-user. 

OPTIONS 

“f  Force.  Do  not  report  errors. 

-R  Recursive,  chgrp  descends  through  the  directory,  and  any  subdirectories,  setting  the  specified 
GID  as  it  proceeds.  When  symbolic  links  are  encountered,  their  group  is  changed,  but  they  are  not 
traversed. 

FILES 

/etc/group 
SEE  ALSO 

chown(2V),  group(5),  passwd(5) 
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NAME 

chkey  -  create  or  change  encryption  key 

SYNOPSIS 

chkey 

DESCRIPTION 

chkey  prompts  the  user  for  their  login  password,  and  uses  it  to  encrypt  a  new  encryption  key  for  the  user  to 
be  stored  in  the  publickey(5)  database. 

If  the  entry  for  nobody  in  the  /etc/publickey  database  has  not  been  commented  out,  chkey  can  be  used  to 
create  new  entries.  If  this  entry  has  been  commented  out,  chkey  can  only  be  used  to  change  an  existing 
entry. 

SEE  ALSO 

keylogin(l),  publickey(5),  keyserv(8C),  newkey(8) 
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NAME 

chmod  -  change  the  permissions  mode  of  a  file 
SYNOPSIS 

chmod  [  — fR  ]  mode  filename  . . . 

SYNOPSIS 

/usr/5bin/chmod  [  -fR  ]  mode  filename  . . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

Change  the  permissions  (mode)  of  a  file  or  files.  Only  the  owner  of  a  file  (or  the  super-user)  may  change 
its  mode. 

The  mode  of  each  named  file  is  changed  according  to  mode^  which  may  be  absolute  or  symbolic,  as  fol¬ 
lows. 

Absolute  Modes 

An  absolute  mode  is  an  octal  number  constructed  from  the  OR  of  the  following  modes: 

400  Read  by  owner. 

200  Write  by  owner. 

100  Execute  (search  in  directory)  by  owner. 

040  Read  by  group. 

020  Write  by  group. 

010  Execute  (search)  by  group. 

004  Read  by  others. 

002  Write  by  others. 

001  Execute  (search)  by  others. 

4000  Set  user  ID  on  execution. 

2000  Set  group  ID  on  execution  (this  bit  is  ignored  if  the  file  is  a  directory;  it  may  be  set  or  cleared 

only  using  symbolic  mode). 

1000  Sticky  bit,  (see  chmod(2V)  for  more  information). 

Symbolic  Modes 

A  symbolic  mode  has  the  form; 

[  who  ]  op  permission  [  op  permission  ] . . . 

who  is  a  combination  of: 

u  User’s  permissions, 

g  Group  permissions, 

o  Others, 

a  All,  or  ugo. 

If  who  is  omitted,  the  default  is  a,  but  the  setting  of  the  file  creation  mask  (see  umask  in  sh(l)  or 
csh(I)  for  more  information)  is  taken  into  account.  When  who  is  omitted,  chmod  will  not  over¬ 
ride  the  restrictions  of  your  user  mask. 

op  is  one  of: 

+  To  add  the  permission. 

-  To  remove  the  permission . 

=  To  assign  the  permission  explicitly  (all  other  bits  for  that  category,  owner,  group,  or  oth¬ 

ers,  will  be  reset). 
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permission  is  any  combination  of: 

r  Read, 

w  Write. 

X  Execute. 

X  Give  execute  pennission  if  the  file  is  a  directory  or  if  there  is  execute  permission  for  one 
of  the  other  user  classes. 

s  Set  owner  or  group  ID.  This  is  only  useful  with  u  or  g.  Also,  the  set  group  ID  bit  of  a 

directory  may  only  be  modified  with  or 

t  Set  the  sticky  bit  to  save  program  text  between  processes. 

The  letters  u,  g,  or  o  indicate  that  permission  is  to  be  taken  from  the  current  mode  for  the  user- 
class. 

Omitting  permission  is  only  useftjl  with  *=’,  to  take  away  all  permissions. 

Multiple  symbolic  modes,  separated  by  commas,  may  be  given.  Operations  are  performed  in  the  order 
specified. 

SYSTEM  V  DESCRIPTION 

If  who  is  omitted  in  a  symbolic  mode,  it  does  not  take  the  file  creation  mask  into  account,  but  acts  as  if  who 
were  a. 

OPTIONS 

-f  Force,  chmod  will  not  complain  if  it  fails  to  change  the  mode  of  a  file. 

-R  Recursively  descend  through  directory  arguments,  setting  the  mode  for  each  file  as  described 
above.  When  symbolic  links  are  encountered,  their  mode  is  not  changed  and  they  are  not 
traversed. 

EXAMPLES 

The  first  example  denies  write  permission  to  others,  the  second  makes  a  file  executable  by  all  if  it  is  execut¬ 
able  by  anyone: 

exainple%  chmod  o-w  file 
exainple%  chmod  +X  file 

SEE  ALSO 

csh(l),  Is(lV),  sh(l),  chmod(2V),  chowii(8) 
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NAME 

clear  -  clear  the  terminal  screen 

SYNOPSIS 

clear 

DESCRIPTION 

clear  clears  your  screen  if  this  is  possible.  It  looks  in  the  environment  for  the  terminal  type  and  then  in 
/etc/termcap  to  figure  out  how  to  clear  the  screen. 

FILES 

/etc/termcap  terminal  capability  data  base 
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NAME 

clear_colomiap  -  clear  the  colormap  to  make  console  text  visible 
SYNOPSIS 

clear_colormap  [  —no  ]  [  -f framebuffer  ] 

DESCRIPTION 

clear_€olormap  ensures  that  text  displayed  on  the  console  is  visible.  If  no  options  are  specified  it  clears 
the  frame  buffer  and  initializes  the  colormap  entries  for  the  first  two  colors  and  the  last  color.  If  the  frame 
buffer  has  an  overlay  plane  it  is  also  cleared,  its  colormap  is  initialized,  and  the  overlay  enable  plane  is  set 
so  that  the  entire  overlay  plane  is  displayed. 

OPTIONS 

-n  Do  not  clear  the  frame  buffer  or  overlay  plane. 

-0  Do  not  clear  the  overlay  plane,  initialize  its  colormap,  or  modify  the  overlay  enable  plane. 

-f  framebuffer 

Operate  on  frame  buffer  devicG  framebuffer  instead  of  the  default,  /dev/fb, 

FILES 

/dev/fb 
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NAME 

clear_functions  --  reset  the  selection  service  to  clear  stuck  function  keys 

SYNOPSIS 

clear_functions 

DESCRIPTION 

c1ear_functions  instructs  the  selection  service  that  no  function  keys  are  currently  depressed.  It  is  useful  in 
cases  where  erroneous  programs  have  reported  a  key  press  but  not  the  corresponding  release.  The  usual 
symptom  for  this  situation  is  that  all  selections  are  secondary  (underscored  rather  than  inverted),  even 
though  no  function  keys  are  down. 

FILES 

/usr/biii/selection_svc 
SEE  ALSO 

SunView  User's  Guide 
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NAME 

click  “  enable  or  disable  the  keyboard’s  keystroke  click 
SYNOPSIS 

click  [  -y  ]  [  -n  ]  [  -d  keyboard-device  ] 

DESCRIPTION 

Change  the  setting  of  the  audible  keyboard  click.  The  default  is  no  keyboard  click.  If  you  want  to  turn 
clicking  on  then  a  good  place  to  do  it  is  in  /etc/rc.locaI. 

Only  keyboards  that  support  a  clicker  respond  to  this  command.  At  the  time  of  this  writing,  the  only  key¬ 
boards  known  to  have  a  clicker  are  the  Sun-3  and  Sun386i  systems  keyboards. 

OPTIONS 

-y  Yes,  enable  clicking. 

-n  No,  disable  clicking. 

-d  keyboard-device 

Specify  the  keyboard  device  being  set.  The  default  is  /dev/kbd. 

FILES 

/etc/rc.local 

/dev/kbd 

SEE  ALSO 

kbd(4S) 

DIAGNOSTICS 

A  short  help  message  is  printed  if  an  unknown  flag  is  specified  or  if  the  -d  switch  is  used  and  the  keyboard 
device  name  is  not  supplied.  A  diagnostic  is  printed  if  the  keyboard  device  name  can’t  be  opened  or  is  not 
a  keyboard  type  device. 

BUGS 

There  is  no  way  to  determine  the  state  of  the  keyboard  click  setting. 
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NAME 

clock  -  display  the  time  in  an  icon  or  window 
SYNOPSIS 

clock  [  -first  ]  [  -d  mdyaw  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User's  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

clock  is  a  SunView  utility  that  displays  the  current  time  in  a  window.  When  open,  clock  shows  the  date 
and  time  in  text  format.  When  closed,  clock  displays  a  clock  face. 

Note:  In  previous  releases  clock  was  known  as  clocktool.  In  the  cuirent  release,  /usr/old/clocktool  is  a 
symbolic  link  to  clock. 

OPTIONS 

-f  Display  the  date  and  day  of  week  on  the  clock  face. 

-r  Use  a  square  face  with  roman  numerals  in  the  iconic  state.  This  replaces  the  default  round  clock 
face. 

-s  Start  clock  with  the  seconds  turned  on.  By  default,  the  clock  starts  with  seconds  turned  off,  and 
updates  every  minute.  With  seconds  turned  on,  it  updates  every  second,  and,  if  iconic,  displays  a 
second  hand. 

-t  Test  mode  —  ignore  the  real  time,  and  instead  run  in  a  loop  continuously  incrementing  the  time  by 
one  minute  and  displaying  it. 

-d  Display  date  information  in  a  small  area  just  below  the  clock  face.  The  date  information  to  be 
displayed  may  include: 
m  the  month, 

d  theday  of  the  month  (1-31), 

y  the  year, 

a  the  string  AM  or  PM,  as  appropriate, 

w  the  day  of  the  week  (Sun-Sat). 

There  is  only  room  for  3  of  these,  but  any  3  may  be  displayed  in  any  sequence, 
clock  also  accepts  all  of  the  generic  tool  arguments  discussed  in  sunview(l). 

USAGE 

clock  listens  for  keyboard  input  while  open.  It  recognizes  the  following  characters: 
s  or  S  Enable  or  disable  the  display  of  seconds, 
t  or  T  Enable  or  disable  “test”  mode. 

FILES 

/usr/lib/fonts/fixedwidthfonts/sail.r.6 

font  for  day-of-month  clock-face  display 

SEE  ALSO 

date(lV),  sunview(l) 

NOTES 

When  the  -r  option  is  specified,  clock  displays  the  roman  numeral  four  as  IHI  instead  of  IV  to  counterbal¬ 
ance  the  roman  numeral  eight,  VIII. 
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BUGS 

If  you  reset  the  system  time,  clock  will  not  reflect  the  new  time  until  you  change  its  state  from  open  to  icon, 
or  vice  versa.  To  reset  the  system  time,  see  date(l  V). 

The  date  display  does  not  go  well  with  the  round  clock  face. 
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NAME 

cluster  -  find  the  Application  SunOS  or  Developer’s  Toolkit  optional  cluster  containing  a  file 
SYNOPSIS 

cluster  [filename  ] 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4,1  release 
feature. 

DESCRIPTION 

cluster  finds  the  optional  software  cluster  that  contains  a  specified  file.  If  the  specified  file  is  contained  in 
one  of  the  clusters  in  Application  SunOS  or  Developer’s  Toolkit,  the  name  of  the  cluster  will  be  printed  on 
standard  output. 

Without  arguments,  cluster  displays  a  summary  of  the  clusters  in  Application  SunOS  and  Developers 
Toolkit,  including  the  load  state  and  size  of  each  cluster. 

EXAMPLES 

To  find  the  name  of  the  cluster  that  contains  the  spell  command: 

example  %  cluster  spell 
spellcheck 
example  % 

To  display  a  summary  of  the  clusters  in  Application  SunOS  and  Developer’s  Toolkit: 

%  cluster 

Application  SunOS  Clusters: 

available  cluster  size  (bytes) 

yes  accounting  265K 

no  advanced_admin  501K 


Developer’s  Toolkit  Clusters: 
availablecluster  size  (bytes) 

no  basedevel  6907K 


space  used  by  clusters:  6021K  bytes 
total  space  remaining:  20432K  bytes 

A  cluster  is  available  if  it  has  been  “loaded”  using  load(l)  or  if  it  has  been  “mounted”  across  the  network. 

FILES 

/usr/lib/load/*  data  files 

SEE  ALSO 

load(l),  unload(l),  toc(5) 

Sun386i  System  Setup  and  Maintenance 
DIAGNOSTICS 

The  file  filename^  not  in  any  of  the  optional  software  clusters. 

The  specified  file  is  not  part  of  the  Application  SunOS  or  Developer’s  Toolkit. 
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NAME 

cmdtool  -  run  a  shell  (or  program)  using  the  SunView  text  facility 
SYNOPSIS 

cmdtool  [  “C  ]  [  ”M  bytes  ]  [  -P  count  ]  [  generic-tool-arguments  ]  [  program  [  program-arguments  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

cmdtool  is  the  standard  SunView  support  facility  for  shells  and  other  programs.  When  invoked,  cmdtool 
runs  a  program  (usually  a  shell)  in  a  text-based  command  subwindow.  Characters  typed  on  the  keyboard 
are  inserted  at  the  caret.  If  the  program  is  a  shell,  that  shell  accepts  and  runs  commands  in  the  usual 
manner,  cmdtool  also  supports  programs  that  perform  cursor  motions  directly,  such  as  vi(l). 

The  text  of  the  current  command  line  can  be  edited  using  normal  textedit(l)  functions.  The  command 
subwindow  displays  a  log  of  the  session,  which  can  be  scrolled  through  using  the  scrollbar  (unless  the  com¬ 
mand  does  cursor  motion).  This  log  can  be  edited,  and  saved  by  choosing  the  ‘Store  as  New  File’  item  in 
the  text  facility’s  pop-up  menu.  The  ‘Split  View’  command,  also  in  the  pop-up  menu,  can  be  used  to  create 
two  or  more  independent  views  of  the  log. 

OPTIONS 

-C  Console  cmdtool.  Display  console  messages  in  this  cmdtool,  which  might  otherwise 

appear  in  unexpected  places  on  the  workstation  screen.  Since  a  cmdtool  window  can  be 
scrolled,  console  error  messages  can  be  recorded  for  later  examination. 

”M  bytes  Set  the  log  to  wrap-around  after  the  indicated  number  of  bytes. 

-P  count  Checkpoint  the  log  after  every  set  of  count  editing  operations. 

generic-tool-arguments 

cmdtool  accepts  the  generic  tool  arguments  listed  in  sunview(l). 
program  [  program-arguments  ] 

If  a  program  argument  is  present,  cmdtool  runs  it  and  passes  any  remaining  arguments 
to  that  program .  If  no  program  is  given,  cmdtool  runs  the  program  indicated  by  the 
SHELL  environment  variable,  or  /usr/bin/sh  by  default. 

USAGE 

Refer  to  SunView  User’s  Guide  for  details  on  how  to  use  cmdtool. 

Defaults  Options 

The  following  options  can  be  configured  as  default  settings  using  default5edit(l). 

/Tty/Append_only__log 

When  set  to  TRUE  (the  standard  default)  only  command  lines  can  be  edited.  FALSE  allows  the 
entire  log  to  be  edited.  (See  also  the  description  of  Enable  Edit  below.) 

/Tty/tnsert_makes_caret_visible 

This  entry  allows  you  to  specify  the  method  for  displaying  the  editing  caret 
Same_as_for_text  Use  the  setting  specified  in  the  defaults  for  the  Text  category  (the  standard 
default). 

If_auto_scrolI  If  the  caret  is  showing,  and  an  inserted  NEWLINE  would  position  it  below 
the  bottom  of  the  screen  (as  determined  by  /Text/Lower_context),  the  text 
is  scrolled  to  keep  the  caret  showing.  The  number  of  lines  scrolled  is  deter¬ 
mined  by  the  /Text/Auto_scroIl_by  default.  (See  textedit(l)  for  more 
information.) 
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Always  Scroll  the  caret  back  into  view  whenever  input  would  position  it  off  the 

screen. 

/Tty/Checkpoint_frequency 

If  set  to  0  (the  standard  default)  no  checkpointing  is  done.  For  any  value  greater  than  zero,  a 
checkpoint  is  made  each  time  the  indicated  number  editing  operations  has  been  performed  since 
the  last  checkpoint.  Each  character  typed,  each  Paste,  and  each  Cut  counts  as  an  editing  opera¬ 
tion.  At  each  checkpoint,  an  updated  copy  of  the  log  is  saved  in  a  file  with  a  name  that  is  con¬ 
structed  by  appending  two  percent  signs  (%  %)  to  the  name  of  the  log  file.  By  default,  the  log  file 
has  a  name  of  the  form  /tinp/tty.txt.p/d  (pid  is  the  process  ID  number  of  cmdtool);  the 
corresponding  checkpoint  file  has  a  name  of  the  form  iimpliiyJbLi.nnnnnn  %  %. 

/Tty/Text_wraparound_size 

If  set  to  0  (the  standard  default)  no  wr£q}-around  takes  place;  the  log  file  grows  without  a  specified 
limit.  For  values  greater  than  zero,  wrap-around  occurs  whenever  the  indicated  number  of  charac¬ 
ters  have  been  written  to  the  log  since  the  last  wrap-around.  Characters  that  are  pushed  over  the 
top  are  replaced  by  the  message: 

***  Text  is  lost  because  the  maximum  edit  log  size  has  been  exceeded.  *** 
/Text/Edit_back_char 

Set  the  character  for  erasing  to  the  left  of  the  caret.  Note:  in  cmdtool,  the  ‘stty  erase*  command 
has  no  effect.  Text-based  tools  refer  only  to  the  defaults  database  key  settings.  The  default  is 
DELETE. 

/Text/Edit_back_word 

Set  the  character  for  erasing  the  word  to  the  left  of  the  caret.  The  standard  default  is  CTRL-W. 
/Text/Edit__back_Une 

Set  the  character  for  erasing  all  characters  to  the  left  of  the  caret.  Note:  *stty  kill’  has  no  effect  in 
cmdtool.  The  standard  default  is  CTRL-U. 

The  Command  Subwindow 

The  command  subwindow  is  based  on  the  text  facility,  which  is  described  in  SunView  User's  Guide.  It 
uses  the  same  pop-up  menu  as  the  text  facility,  but  with  an  additional  pull-right  ‘Cmd  Modes’  menu, 
which  contains  the  "Enable  Editing’  and  ‘Disable  Scrolling’  items. 

Command  subwindows  support  cursor  motions,  using  a  new  /etc/termcap  entry  called  sun-cmd.  Com¬ 
mand  subwindows  automatically  set  the  TERM  environment  variable  to  sun-cmd.  So,  if  you  rlogin(lC)  to 
a  machine  that  does  not  have  an  entry  for  sun-cmd  in  its  /etc/termcap  file,  the  error  message  ‘Type  sun- 
cmd  unknown’  results.  To  rectify  this,  type  the  command  ‘set  TERM=sun’.  Programs  written  using  the 
curses(3V)  library  package  will  work  in  a  command  subwindow,  but  programs  hard-coded  for  sun-type 
terminals  may  not.  When  supporting  a  program  that  performs  cursor  motions,  the  command  subwindow 
automatically  takes  on  the  characteristics  of  a  tty  subwindow  (as  with  shelltool(l)).  When  that  program 
terminates  or  sleeps,  the  full  command  subwindow  functionality  is  restored. 

cmdtool  supports  programs  that  use  CBREAK  and  NO  ECHO  terminal  modes.  This  support  is  normally 
invisible  to  the  user.  However,  programs  that  use  RAW  mode,  such  as  rlogin(lC)  and  script(l),  inhibit 
command-line  editing  with  the  mouse.  In  this  case,  however,  tty-style  ERASE,  word-kill  and  line-kill  char¬ 
acters  can  still  be  used  to  edit  the  current  command  line. 

The  Command  Subwindow  Menu 

Copy,  then  Paste  When  there  is  a  current  selection,  the  entire  menu  item  is  active.  The  selection  is 
copied  both  to  the  clipboard  and  to  the  location  pointed  to  by  the  caret.  When  there 
is  no  selection,  but  there  is  text  on  the  clipboard,  only  Paste  is  active.  In  this  case, 
the  contents  of  the  clipboard  are  copied  to  the  caret.  When  there  is  no  selection  and 
the  clipboard  is  empty,  this  item  is  inactive.  ‘Copy  then  Paste’  is  a  generic  text 
menu  item.  Refer  to  textedit(l)  for  information  about  other  generic  text  menu 
items. 
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Enable  Edit 

Disable  Edit  Toggle  to  allow  or  disallow  editing  on  the  log. 

Disable  Scrolling 

Enable  Scrolling  Toggle  between  a  scrollable,  editable  window,  or  a  display  that  supports  cursor 
motions.  Note:  for  well-behaved  programs  (such  as  vi(l))  this  switching  is  per¬ 
formed  automatically  (so  this  menu  item  is  seldom  needed). 

Accelerators 

Text  facility  accelerators  that  are  especially  useful  in  command  subwindows  are  described  here.  See 
textedit(l)  for  more  information. 

CTRL-RETURN  Position  the  caret  at  the  bottom,  and  scroll  it  into  view  as  determined  by 
/Text/Lower_context. 

META-P  Choose  the  ‘Copy,  then  Paste*  menu  item. 

CAPS-lock 

FI  Toggle  between  all-upper-case  keyboard  input,  and  mixed-case. 

ENVIRONMENT 

The  environment  variables  LC^CTYPE,  LANG,  and  LC__default  control  the  character  classification 
throughout  cmdtool.  On  entry  to  cmdtool,  these  environment  variables  are  checked  in  the  following  order: 
LC__CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC  CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSLX.i  “C”  locale. 

FILES 

/tmp/tty.txt.p/d  log  file 

“/.textswrc 

“/.ttyswrc 

usr/libAtext_extras_menu 

/etc/termcap 

SEE  ALSO 

defaultsedit(l),  rlogin(lC),  script(l),  sh(l),  shelltooKl),  sunview(l),  textedit(l),  vi(l),  curs€s(3V) 

Installing  SunOS  4.1 
SunView  User's  Guide 

BUGS 

Typing  ahead  while  cmdtool  changes  between  its  scrollable  and  cursor  motion  modes  will  sometimes 
freeze  cmdtool . 

Full  terminal  emulation  is  not  complete.  Some  manifestations  of  this  deficiency  are: 

•  File  completion  in  the  C  shell  does  not  work. 

•  Enhanced  display  of  text  is  not  supported. 
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NAME 

cmp  “  perform  a  byte-by-byte  comparison  of  two  files 
SYNOPSIS 

cmp  [  -Is  ]  filenamel  filename!  [  skipl  ]  [  skip!  ] 

DESCRIPTION 

cmp  comports  filenamel  md  filename!.  filenamel  is  the  standard  input  is  used.  With  no  options, 
cmp  makes  no  comment  if  the  files  are  the  same;  if  they  differ,  it  reports  the  byte  and  line  number  at  which 
the  difference  occurred,  or,  that  one  file  is  an  initial  subsequence  of  the  other,  skipl  and  skip!  are  initial 
byte  offsets  into  filenamel  and  filename!  respectively,  and  may  be  either  octal  or  decimal;  a  leading  0 
denotes  octal. 

OPTIONS 

-I  Print  the  byte  number  (in  decimal)  and  the  differing  bytes  (in  octal)  for  all  differences  between  the 
two  files. 

-s  Silent  Print  nothing  for  differing  files;  set  exit  codes  only. 

SEE  ALSO 

comm(l),  diff(l) 

DIAGNOSTICS 

Exit  code  0  is  returned  for  identical  files,  1  for  different  files,  and  2  for  an  inaccessible  or  missing  argu¬ 
ment,  or  a  system  error. 
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NAME 

col  ~  filter  reverse  paper  motions  from  nroff  output  for  display  on  a  terminal 

SYNOPSIS 

col  [  “bfhp  ] 

SYSTEM  V  SYNOPSIS 

/usr/5bin/col  [  -bfpx  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

col  copies  the  standard  input  to  the  standard  ouQjut  and  performs  line  overlays  implied  by  reverse 
LINEFEED  characters  (ESC~7  in  ASCII)  and  by  forward  and  reverse  half  LINEFEED  characters  (ESC-9  and 
ESC-8).  col  is  particularly  useful  for  filtering  multicolumn  output  made  with  the  ,rt  command  of  nroff(l), 
and  output  resulting  from  use  of  the  tbl(l)  preprocessor. 

The  control  characters  SO  (ASCII  code  017),  and  SI  (016)  are  assumed  to  start  and  end  text  in  an  alternate 
character  set.  The  character  set  (primary  or  alternate)  associated  with  each  printing  character  read  is 
remembered;  on  output,  SO  and  SI  characters  are  generated  where  necessary  to  maintain  the  correct  treat¬ 
ment  of  each  character. 

All  control  characters  are  removed  from  the  input  except  SPACE,  BACKSPACE,  TAB,  RETURN,  NEWLINE, 
ESC  (033)  followed  by  one  of  7,  8, 9,  SI ,  SO ,  and  VT  (013).  This  last  character  is  an  alternate  form  of  full 
reverse  LINEFEED,  for  compatibility  with  some  other  hardware  conventions.  All  other  non-printing  char¬ 
acters  are  ignored. 

SYSTEM  V  DESCRIPTION 

The  System  V  version  of  col  converts  SPACE  to  TAB  characters  by  default. 

OPTIONS 

-b  The  output  device  in  use  is  not  capable  of  backspacing.  In  this  case,  if  several  characters  are  to 
appear  in  the  same  place,  only  the  last  one  read  will  be  taken. 

-f  Fine.  Although  col  accepts  half  line  motions  in  its  input,  it  normally  does  not  produce  them  on 
output.  Instead,  text  that  would  appear  between  lines  is  moved  to  the  next  lower  full-line  boun¬ 
dary.  The  -f  option  suppresses  this  treatment.  In  this  case  the  output  from  col  may  contain  for¬ 
ward  half  LINEFEED  characters  (ESC-9),  but  will  still  never  contain  either  kind  of  reverse  line 
motion. 

-h  Convert  strings  of  blanks  to  TAB  characters  to  decrease  the  printing  time. 

-p  Pass  escape-sequences  that  col  does  not  know  about  to  the  output,  rather  than  stripping  them  out. 

This  option  is  highly  discouraged  unless  you  are  fully  aware  of  the  position  of  the  escape 
sequences  within  the  text. 

SYSTEM  V  OPTIONS 

—X  Suppress  converting  SPACE  characters  to  TAB  characters. 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  col.  On  entry  to  col,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSDC.l  “C”  locale. 

SEE  ALSO 

nroff(l),  tbl(l),  troff(l),  locale(5),  iso  J859_l(7) 
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BUGS 

col  cannot  back  up  more  than  128  lines. 

At  most  1600  characters,  including  BACKSPACE  characters,  are  allowed  on  a  line. 

Local  vertical  motions  that  would  result  in  backing  up  over  the  first  line  of  the  document  are  ignored.  As  a 
result,  the  first  line  must  not  have  any  superscripts. 
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NAME 

colcrt  -  filter  nroff  output  for  a  terminal  lacking  overstrike  capability 
SYNOPSIS 

colcrt  [  ”  ]  [  -2  ]  [filename  . . .  ] 

DESCRIPTION 

colcrt  provides  virtual  half  and  reverse  LINEFEED  sequences  for  terminals  without  such  capability,  and  on 
which  overstriking  is  destructive.  Half  LINEFEED  characters  and  underlining  (changed  to  dashing  are 
placed  on  new  lines  in  between  the  normal  output  lines. 

OPTIONS 

-  Suppress  all  underlining  —  especially  useful  for  previewing  allboxed  tables  from  tbl(l). 

-2  Print  all  half  LINEFEED  characters,  effectively  double  spacing  the  output.  Normally,  a  minimal 

space  output  format  is  used  which  suppresses  empty  lines,  colcrt  never  suppresses  two  consecu¬ 
tive  empty  lines,  however.  The  —2  option  is  useful  for  sending  output  to  the  line  printer  when  the 
output  contains  superscripts  and  subscripts  which  would  otherwise  be  invisible. 

EXAMPLE 

A  typical  use  of  colcrt  would  be 

example%  tbi  exum2.n  |  nroff -ms  |  colcrt  - 1  more 

SEE  ALSO 

coI(lV),  more(i),  nroff(l),  tbl(l),  troff(l),  ul(l) 

BUGS 

Cannot  back  up  more  than  102  lines. 

General  overstriking  is  lost;  as  a  special  case  ‘  |  ’  overstruck  with  ‘  ’  or  underline  becomes  *  + 

Lines  are  trimmed  to  132  characters. 

Some  provision  should  be  made  for  processing  superscripts  and  subscripts  in  documents  which  are  already 
double-spaced. 
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NAME 

coloredit  -  alter  color  map  segment 

SYNOPSIS 

coloredit 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

coloredit  is  a  SunView  application  for  altering  the  colors  of  objects  (windows)  selected  with  the  cursor. 
These  colors  may  be  manipulated  in  three  ways: 

•  select  color  name  from  a  list 

•  specify  the  hue/saturation/value  for  a  color 

•  specify  the  red/green/blue  levels  for  a  color 

USAGE 

Window 

The  coloredit  window  consists  of  four  sections. 

colorlist  An  interactive  window  that  lists  the  available  colors  for  selection.  This  list  can  be  scrolled 
up  and  down  with  a  scrollbar,  and  comprises  the  contents  of  the  .rgb  file.  Select  a  color  and 
the  corresponding  RGB  and  HSV  value  appears  in  the  colorbar  section,  coloredit  first 
searches  the  working  directory  for  .rgb,  your  home  directory,  and  finally,  /usr/lib  this  file. 

colorbars  An  interactive  window  with  two  sets  of  three  sliding  bars.  One  set  is  for  defining  the  hue 
saturation  value  of  the  color  desired.  The  second  set  is  for  defining  the  red-green-blue 
ratios.  The  color  can  be  specified  using  either  set  of  sliding  bars. 

palette  A  display  subwindow  divided  horizontally  into  two  equal  parts.  The  top  part  shows  the 

background  color;  the  bottom,  the  foreground  color.  If  the  object  has  more  than  2  colors,  all 
the  colors  are  shown.  The  background  color  is  color  Index  #0.  The  color  with  the  highest 
Index  Number  is  the  foreground  color. 

logo  A  display  subwindow  containing  the  Sun  logo  in  the  currently-selected  color. 

Command  Buttons 

The  set  of  command  buttons  in  the  colorbars  subwindow  is  as  follows. 

Grab  The  next  object  selected  will  have  its  color  map  segment  colors  displayed  in  the  coloredit  win¬ 
dow.  These  colors  may  then  be  manipulated. 

Release  Disassociates  the  colormap  segment  and  the  last  object  with  which  those  colors  were  associated. 
The  window  returns  to  its  default  slate. 

Undo  Returns  the  colormap  segment  to  the  original  colors  that  the  object  being  colored  had  when  color¬ 
ing  began.  Returns  the  object  to  its  original  colors. 

FILES 

y.rgb 

‘/.rgb 

/usr/Iib/.rgb 

SEE  ALSO 

sunview(l) 
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NAME 

colrm  -  remove  characters  from  specified  columns  within  each  line 
SYNOPSIS 

colrm  [  startcol  [  endcol  ]  ] 

DESCRIPTION 

colrm  removes  selected  columns  from  a  text  file.  The  text  is  taken  from  standard  input  and  copied  to  the 
standard  output  with  the  specified  columns  removed. 

If  only  startcol  is  specified,  the  columns  of  each  line  are  removed  starting  with  startcol  and  extending  to 
the  end  of  the  line.  If  both  startcol  and  endcol  are  specified,  all  columns  between  startcol  and  endcol, 
inclusive,  are  removed. 

Column  numbering  starts  with  column  1. 

SEE  ALSO 

expand(l) 
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NAME 

comm  -  display  lines  in  common,  and  lines  not  in  common,  between  two  sorted  lists 
SYNOPSIS 

comm  [  -1 1  -2 1  “3 1  -12 1  -13 1  -23  ]  filenamel  filename! 

DESCRIPTION 

comm  reads  filenamel  and  filename! ,  which  should  be  ordered  in  ASCII  collating  sequence  (see  sort(lV)), 
and  produces  three-column  output  when  no  options  are  specified: 

•  Column  1  contains  lines  that  occur  only  in  filenamel . 

•  Column  2  contains  lines  only  in  filename! . 

•  Column  3  contains  lines  common  to  both  files. 

The  filename  *-*  means  the  standard  input. 

OPTIONS 

The  following  options  can  be  used  to  suppress  the  indicated  columns  fi:om  display.  You  can  specify 
*-123’,  but  doing  so  suppresses  all  output. 

-1  Suppress  column  1;  omit  lines  only  in  filenamel . 

-2  Suppress  column  2;  omit  lines  only  in  filename! . 

-3  Suppress  column  3;  omit  lines  common  to  both  files. 

-12  Suppress  columns  1  and  2;  only  show  lines  common  to  both  files. 

-13  Suppress  columns  1  and  3;  only  show  lines  in  filename! . 

“23  Suppress  columns  2  and  3;  only  show  lines  in  filenamel . 

SEE  ALSO 

cmp(l),  diff(l),  sort(lV),  uniq(l) 

BUGS 

The  options  suppress^  rather  than  select  the  columns  you  indicate. 
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NAME 

compress,  uncompress,  zcat  -  compress  or  expand  files,  display  expanded  contents 
SYNOPSIS 

compress  [  -cfv  ]  [  -b  bits  ]  [filename. . .  ] 
uncompress  [  -cv  ]  [filename.. .  ] 
zcat  [filename. . .  ] 

DESCRIPTION 

compress  reduces  the  size  of  the  named  files  using  adaptive  Lempel-Ziv  coding.  Whenever  possible,  each 
file  is  replaced  by  one  with  the  extension  .Z,  while  keeping  the  same  ownership  modes,  as  well  as  access 
and  modification  times.  If  no  files  are  specified,  the  standard  input  is  compressed  to  the  standard  output. 

The  amount  of  compression  obtained  depends  on  the  size  of  the  input,  the  number  of  bits  per  code,  and  the 
distribution  of  common  substrings.  Typically,  text  such  as  source  code  or  English  is  reduced  by  50-60%. 
Compression  is  generally  much  better  than  that  achieved  by  Huffman  coding  (as  used  in  sys-unconfig(8)), 
or  adaptive  Huffman  coding  (old-€ompact(l)),  and  takes  less  time  to  compute.  The  bits  parameter 
specified  during  compression  is  encoded  within  the  compressed  file,  along  with  a  magic  number  to  ensure 
that  neither  decompression  of  random  data  nor  recompression  of  compressed  data  is  subsequently  allowed. 

Compressed  files  can  be  restored  to  their  original  form  using  uncompress, 
zcat  produces  uncompressed  output  on  the  standard  output,  but  leaves  the  compressed  .Z  file  intact 
OPTIONS 

-c  Write  to  the  standard  output;  no  files  are  changed.  The  nondestructive  behavior  of  zcat  is  identi¬ 
cal  to  that  of  'uncompress  ~c’. 

-f  Force  compression,  even  if  the  file  does  not  actually  shrink,  or  the  corresponding  .  Z  file  already 
exists.  Except  when  running  in  the  background  (under  sh(l)),  if  -f  is  not  given,  prompt  to  verify 
whether  an  existing .  Z  file  should  be  overwritten. 

-V  Verbose.  Display  the  percentage  reduction  for  each  file  compressed. 

-b  bits  Set  the  upper  limit  (in  bits)  for  common  substring  codes,  bits  must  be  between  9  and  16  (16  is  the 
default). 

SEE  ALSO 

In(lV),  old-compact(l),  sh(l),  sys-unconfig(8) 

A  Technique  for  High  Performance  Data  Compression,  Terry  A.  Welch,  computer,  vol.  17,  no.  6  (June 
1984),  pp.  8-19. 

DIAGNOSTICS 

Exit  status  is  normally  0.  If  the  last  file  was  not  compressed  because  it  became  larger,  the  status  is  2.  If  an 
error  occurs,  exit  status  is  1. 

Usage:  compress  [-fvc]  ["b  maxbits]  [filename. . .] 

Invalid  options  were  specified  on  the  command  line. 

Missing  maxbits 

Maxbits  must  follow  -b  . 

filename:  not  in  compressed  format 

The  file  specified  to  uncompress  has  not  been  compressed. 

filename:  compressed  with  xrbits,  can  only  handle  yy bits 

filename  was  compressed  by  a  program  that  could  deal  with  more  bits  than  the  compress  code 
on  this  machine.  Recompress  the  file  with  smaller  bits. 
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filename:  already  has .  Z  suffix  -  no  change 

The  file  is  assumed  to  be  already  compressed.  Rename  the  file  and  try  again. 

filename:  already  exists;  do  you  wish  to  overwrite  (y  or  n)? 

Respond  y  if  you  want  the  output  file  to  be  replaced;  n  if  not. 

uncompress:  corrupt  input 

A  SIGSEGV  violation  was  detected,  which  usually  means  that  the  input  file  is  corrupted. 
Compression:  jocjcc% 

Percentage  of  the  input  saved  by  compression,  (Relevant  only  for  -v.) 

—  not  a  regular  file:  unchanged 

When  the  input  file  is  not  a  regular  file,  (such  as  a  directory),  it  is  left  unaltered. 

—  has  XX  other  links:  unchanged 

The  input  file  has  links;  it  is  left  unchanged.  See  In(lV)  for  more  information. 

—  file  unchanged 

No  savings  are  achieved  by  compression.  The  input  remains  uncompressed. 


BUGS 

Although  compressed  files  are  compatible  between  machines  with  large  memory,  -bl2  should  be  used  for 
file  transfer  to  architectures  with  a  small  process  data  space  (64KB  or  less). 

compress  should  be  more  flexible  about  the  existence  of  the .  Z  suffix. 
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NAME 

cp  -  copy  files 
SYNOPSIS 

cp  [  -ip  ]Jilenamel  filename2 
cp  -rR  [  -ip  ]  directory  1  directory! 
cp  [  -iprR  filename  . . .  directory 

DESCRIPTION 

cp  copies  contents  offilenamel  onto  filename! .  The  mode  and  owner  of  filename!  are  preserved  if  it 
already  existed;  the  mode  of  the  source  file  is  used  otherwise.  If  filenamel  is  a  symbolic  link,  or  a  dupli¬ 
cate  hard  link,  the  contents  of  the  file  that  the  link  refers  to  are  copied;  links  are  not  preserved. 

In  the  second  form,  cp  recursively  copies  directory! ,  ^ong  with  its  contents  and  subdirectories,  to  direc- 
tory!  .  If  directory!  does  not  exist,  cp  creates  it  and  duplicates  the  files  and  subdirectories  of  directory! 
within  it  If  directory!  does  exist,  cp  makes  a  copy  of  the  directory!  directory  within  directory!  (as  a  sub¬ 
directory),  along  with  its  files  and  subdirectories. 

In  the  third  fonn,  each  filename  is  copied  to  the  indicated  directory;  the  basename  of  the  copy  corresponds 
to  that  of  the  original.  The  destination  directory  must  already  exist  for  the  copy  to  succeed. 

cp  refuses  to  copy  a  file  onto  itself. 

OPTIONS 

— i  Interactive.  Prompt  for  confirmation  whenever  the  copy  would  overwrite  an  existing  file.  A  y  in 

answer  confirms  that  the  copy  should  proceed.  Any  other  answer  prevents  cp  from  overwriting 
the  file. 

-p  Reserve.  Duplicate  not  only  the  contents  of  the  original  file  or  directory,  but  also  the  modification 
time  and  permission  modes. 

-r 

-R  Recursive.  If  any  of  the  source  files  are  directories,  copy  the  directory  along  with  its  files  (includ¬ 
ing  any  subdirectories  and  their  files);  the  destination  must  be  a  directory. 

EXAMPLES 

To  copy  a  file: 

example  %  cp  goodies  goixlies.old 
example  %  Is  goodies* 
goodies  goodies.old 

To  copy  a  directory,  first  to  a  new,  and  then  to  an  existing  destination  directory: 

example%  Is  7bkup 
/usr/example/fred/bkup  not  found 
example  %  cp  -r  7src  7bkup 
example  %  Is  -R  7bkup 
X.C  y.c  z.sli 

example  %  cp  -r  7src  7bkup 
example  %  Is  ~R  7bkup 
sre  X.C  y*c  z,sh 

sre: 

X.C  y.c  z.sh 

To  copy  a  list  of  files  to  a  destination  directory: 
example%  cp  7src/*  /tmp  • 

SEE  ALSO 

cat(lV),  In(lV),  mv(l),  pr(lV),  rcp(lC),  tar(l) 
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WARNINGS 

Beware  of  a  recursive  copy  like  this: 

example  %  cp  -r  7src  "/src/bkup 
which  keeps  copying  files  until  it  fills  the  entire  file  system. 

BUGS 

Cp  copies  the  contents  of  files  pointed  to  by  symbolic  links.  It  does  not  copy  the  symbolic  link  itself.  This 
can  lead  to  inconsistencies  when  directory  hierarchies  are  replicated.  Filenames  that  were  linked  in  the  ori¬ 
ginal  hierarchy  are  no  longer  linked  in  the  replica.  This  is  also  true  for  files  with  multiple  hard  links.  See 
In(lV)  for  details  about  symbolic  links  and  hard  links.  You  can  preserve  links  in  replicated  hierarchies  by 
using  tar(l)  to  copy  them. 


88 


Last  change:  9  September  1987 


Sun  Release  4.1 


CPIO(l) 


USER  COMMANDS 


CPIO(l) 


NAME 

cpio  -  copy  file  archives  in  and  out 

SYNOPSIS 

cpio  -o  [  aBcv  ] 

cpio  -i  [  bBcdfmrsStuv6  ]  [  patterns  ] 
cpio  -p  [  adlmuv  ]  directory 

DESCRIPTION 

cpio  copies  files  in  to  and  out  from  a  cpio  copy  archive.  The  archive  (built  by  ‘cpio  -o’)  contains  path¬ 
name  and  status  information,  along  with  the  contents  of  one  or  more  archived  files. 

OPTIONS 

-o  Copy  out  an  archive.  Read  the  standard  input  for  a  list  of  pathnames,  then  copy  the  named  files  to 
the  standard  output  in  archive  form  —  including  pathname  and  status  information. 

a  Reset  the  access  times  of  input  files  after  they  have  been  copied. 

B  Output  is  to  be  blocked  at  5120  bytes  to  the  record.  This  does  not  apply  to  the  pass 

option.  This  option  is  only  meaningful  with  data  directed  to  raw  magnetic  devices,  such 
as  Vdev/rmt.?’. 

c  Write  header  information  in  ASCII  character  form  for  portability. 

v  Verbose.  A  list  of  filenames  is  displayed.  When  used  with  the  t  option,  the  table  of  con¬ 
tents  looks  like  the  output  of  an  ‘Is  -I’  command  (see  Is(lV)). 

-i  Copy  in  an  archive.  Read  in  an  archive  from  the  standard  input  and  extract  files  with  names 
matching  filename  substitution  patterns,  supplied  as  arguments. 

patterns  are  similar  to  those  in  sh(l)  or  csh(l),  save  that  within  cpio,  the  metacharacters  *?’, 
and  *[  ...  1’  also  match  the  V’  (slash)  character.  If  no  patterns  are  specified,  the  default  is  * 
(select  all  files). 

b  Swap  both  bytes  and  half-words  after  reading  in  data. 

B  Input  is  to  be  blocked  at  5120  bytes  to  the  record.  This  does  not  apply  to  the  pass  option. 
This  option  is  only  meaningful  with  data  received  from  raw  magnetic  devices,  such  as 
Vdev/rmt.?’. 

d  Create  directories  as  needed, 
f  Copy  in  all  files  except  those  matching  patterns. 

m  Retain  previous  file  modification  time.  This  option  is  ineffective  on  directories  that  are 
being  copied. 

r  Interactively  rename  files.  If  the  user  types  a  null  line,  the  file  is  skipped.  May  not  be 
used  with  the  ~p  option. 

s  Swap  bytes  after  reading  in  data. 

5  Swap  halfwords  after  reading  in  data, 

t  Print  a  table  of  contents  of  the  input  archive.  No  files  are  created. 

u  Copy  unconditionally.  Normally,  an  older  file  will  not  replace  a  newer  file  with  the  same 
name. 

6  Process  UNIX  Version-6  files. 

-p  One  pass.  Copy  in  and  out  in  a  single  operation.  Destination  pathnames  are  interpreted  relative  to 
the  named  directory. 

1  Whenever  possible,  link  files  rather  than  copying  them. 
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EXAMPLES 

To  copy  the  contents  of  a  directory  into  an  archive: 

example  %  Is  |  cpio  -o  >  /dev/m tO 

To  read  a  cpio  archive  from  a  tape  drive: 

example  %  cpio  -icdB  <  /dev/rmtO 

To  duplicate  the  olddir  directory  hierarchy  in  the  newdir  directory: 
example  %  cd  olddir 

example  %  find .  -depth  -print  |  cpio  -pdl  newdir 
The  trivial  case 

example%  find  .  -depth  -print  |  cpio  -oB  >/dev/rmtO 
can  be  handled  more  efficiently  by: 

exam  pie  %  find  .  -cpio  /dev/rmt/Om 

cpio  archive  tapes  from  other  sites  may  have  bytes  swapped  within  the  archive.  Although  the  -is  option 
only  swaps  the  data  bytes  and  not  those  in  the  header  cpio  recognizes  tapes  like  this  and  swaps  the  bytes  in 
the  header  automatically. 

SEE  ALSO 

ar(lV),  csh(l),  find(l),  Is(lV),  sh(l),  tar(l),  cpio(5) 

BUGS 

cpio  does  not  support  multiple  volume  tapes. 

Pathnames  are  restricted  to  128  characters.  If  there  are  too  many  unique  linked  files,  cpio  runs  out  of 
memory  and  linking  information  is  lost  thereafter.  Only  the  super-user  can  copy  special  files. 
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NAME 

q>p  “  the  C  language  preprocessor 
SYNOPSIS 

/usr/lib/cpp  [  -BCHMpPRT  ]  [  -undef  ]  [  -Dname  ]  [  -Dname=d^]  [  -Idirectory  ]  [  -Vname  ] 

[  -Y directory  ]  [  input-file  [  output-file  ]  ] 

DESCRIPTION 

cpp  is  the  C  language  preprocessor.  It  is  invoked  as  the  first  pass  of  any  C  compilation  started  with  the 
cc(lV)  command;  however,  cpp  can  also  be  used  as  a  first-pass  preprocessor  for  other  Sun  compilers. 

Although  cpp  can  be  used  as  a  macro  processor,  this  is  not  normally  recommended,  as  its  output  is  geared 
toward  that  which  would  be  acceptable  as  input  to  a  compiler’s  second  pass.  Thus,  the  preferred  way  to 
invoke  cpp  is  through  the  cc(lV)  command,  or  some  other  compilation  command.  For  general-purpose 
macro-processing,  see  m4(l  V),  and  the  chapter  on  iii4  in  Programming  Utilities  and  Libraries. 

cpp  optionally  accepts  two  filenames  as  arguments,  input-file  and  output-file  are,  respectively,  the  input 
and  output  files  for  the  preprocessor.  They  default  to  the  standard  input  and  the  standard  output. 

OPTIONS 

-B  Support  the  C++  comment  indicator  7/’.  With  this  indicator  everything  on  the  line  after  the  //  is 
treated  as  a  comment. 

~C  Pass  all  comments  (except  those  that  appear  on  cpp  directive  lines)  through  the  preprocessor.  By 
default,  cpp  strips  out  C-style  comments. 

-H  Print  the  pathnames  of  included  files,  one  per  line  on  the  standard  error. 

-M  Generate  a  list  of  makefile  dependencies  and  write  them  to  the  standard  output  This  list  indicates 

that  the  object  file  which  would  be  generated  from  the  input  file  depends  on  the  input  file  as  well 
as  the  include  files  referenced. 

-p  Use  only  the  first  eight  characters  to  distinguish  preprocessor  symbols,  and  issue  a  warning  if 
extra  tokens  appear  at  the  end  of  a  line  containing  a  directive. 

“P  Preprocess  the  input  without  producing  the  line  control  information  used  by  the  next  pass  of  the  C 
compiler. 

-R  Allow  recursive  macros. 

-T  Use  only  the  first  eight  characters  for  distinguishing  different  preprocessor  names.  This  option  is 
included  for  backward  compatibility  with  systems  which  always  use  only  the  first  eight  characters. 

-undef  Remove  initial  definitions  for  all  predefined  symbols. 

-Dname 

Define  name  as  1  (one).  This  is  the  same  as  if  a  -Dname =1  option  appeared  on  the  cpp  command 
line,  or  as  if  a 

#define  name  1 

line  appeared  in  the  source  file  that  cpp  is  processing. 

-Dname  =d^ 

Define  name  as  if  by  a  #define  directive.  This  is  the  same  as  if  a 
#define  name  def 

line  appeared  in  the  source  file  that  cpp  is  processing.  The  -D  option  has  lower  precedence  than 
the  -U  option.  That  is,  if  the  same  name  is  used  in  both  a  -U  option  and  a  -D  option,  the  name 
will  be  undefined  regardless  of  the  order  of  the  options. 
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-Idirectory 

Insert  directory  into  the  search  path  for  #include  files  with  names  not  beginning  with  *I\  direc¬ 
tory  is  inserted  ahead  of  the  standard  list  of  “include’’  directories.  Thus,  #include  files  with 
names  enclosed  in  double-quotes  (")  are  searched  for  first  in  the  directory  of  the  file  with  the 
#include  line,  then  in  directories  named  with  -I  options,  and  lastly,  in  directories  from  the  stan¬ 
dard  list.  For#include  files  with  names  enclosed  in  angle-brackets  (<>),  the  directory  of  the  file 
with  the  #include  line  is  not  searched.  See  Details  below  for  exact  details  of  this  search  order, 

-IJname 

Remove  any  initial  definition  of  name,  where  name  is  a  symbol  that  is  predefined  by  a  particular 
preprocessor.  Here  is  a  partial  list  of  symbols  that  may  be  predefined,  depending  upon  the  archi¬ 
tecture  of  the  system: 

Operating  System:  ibm,  geos,  os,  tss  and  unix 

Hardware:  interdata,  pdpll,  u370,  u3b,  u3b2,  u3b5,  u3bl5,  u3b20d,  vax, 

ns32000,  iAPX286,  i386,  spare  ,  and  sun 
UNIX  system  variant:  RES,  and  RT 
The  lint(lV)  command:  lint 

The  symbols  sun  and  unix  are  defined  for  all  Sun  systems,  as  is  the  value  returned  by  the  mach 
command.  For  Sun-4  systems,  this  value  would  be  spare. 

~Y  directory 

Use  directory  directory  in  place  of  the  standard  list  of  directories  when  searching  for  #mclude 
files. 


USAGE 

Directives 

All  epp  directives  start  with  a  hash  symbol  (#)  as  the  first  character  on  a  line.  White  space  (SPACE  or  TAB 
characters)  can  appear  after  the  initial  #  for  proper  indentation. 

#define  name  token-string 

Replace  subsequent  instances  of  name  with  token-string. 

#define  name  (argument  [,  argument] ...  )  token-string 

There  can  be  no  space  between  name  and  the  Replace  subsequent  instances  of  name,  fol¬ 
lowed  by  a  parenthesized  list  of  arguments,  with  token-string,  where  each  occurrence  of  an  argu¬ 
ment  in  the  token-string  is  replaced  by  the  corresponding  token  in  the  comma-separated  list. 
When  a  macro  with  arguments  is  expanded,  the  arguments  are  placed  into  the  expanded  token¬ 
string  unchanged.  After  the  entire  token-string  has  been  expanded,  epp  re-starts  its  scan  for 
names  to  expand  at  the  beginning  of  the  newly  created  token-string. 

#undef  name 

Remove  any  definition  for  the  symbol  name.  No  additional  tokens  are  permitted  on  the  directive 
line  after  name. 

#include  "filename  " 

#include  <filename> 

Read  in  the  contents  of  filename  at  this  location.  This  data  is  processed  by  epp  as  if  it  were  part  of 
the  current  file.  When  the  <filename>  notation  is  use^,  filename  is  only  searched  for  in  the  stan¬ 
dard  “include”  directories.  See  the  -I  and  -Y  options  above  for  more  detail.  No  additional 
tokens  are  permitted  on  the  directive  line  after  the  final  ’  or  *>’. 
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#Iine  integer-constant  filename” 

Generate  line  control  information  for  the  next  pass  of  the  C  compiler,  integer-constant  is  inter¬ 
preted  as  the  line  number  of  the  next  line  and  filename  is  interpreted  as  the  file  from  where  it 
comes.  If  ^filename”  is  not  given,  the  current  filename  is  unchanged.  No  additional  tokens  are 
permitted  on  the  directive  line  after  the  option^  filename . 

#if  constant-expression 

Subsequent  lines  up  to  the  matching  #else,  #elif ,  or  #endif  directive,  appear  in  the  output  only  if 
constant-expression  yields  a  nonzero  value.  All  binary  non-assignment  C  operators,  including 
‘I  I’,  and  are  legal  in  constant-expression.  The  *?;’  operator,  and  the  unary  and 

’  operators,  are  also  legal  in  constant-expression. 

The  precedence  of  these  operators  is  the  same  as  that  for  C.  In  addition,  the  unary  operator 
defined,  can  be  used  in  constant-expression  in  these  two  forms:  ‘defined  (  name  )’  or  ‘defined 
name\  This  allows  the  effect  of  #ifdef  and  #ifndef  directives  (described  below)  in  the  #if  direc¬ 
tive.  Only  these  operators,  integer  constants,  and  names  that  are  known  by  cpp  should  be  used 
within  constant-expression.  In  particular,  the  size  of  operator  is  not  available. 

#ifdef  name 

Subsequent  lines  up  to  the  matching  #else,  #elif,  or  #endir  appear  in  the  output  only  if  name  has 
been  defined,  either  with  a  #define  directive  or  a  -D  option,  and  in  the  absence  of  an  intervening 
#undef  directive.  No  additional  tokens  are  permitted  on  the  directive  line  after  name . 

#ifndef  name 

Subsequent  lines  up  to  the  matching  #else,  #elif,  or  #endif  appear  in  the  output  only  if  name  has 
not  been  defined,  or  if  its  definition  has  been  removed  with  an  #undef  directive.  No  additional 
tokens  are  permitted  on  the  directive  line  after  name  . 

#elif  constant-expression 

Any  number  of  #elif  directives  may  appear  between  an  #if,  #ifdef,  or  #irndef  directive  and  a 
matching  #else  or  #endif  directive.  The  lines  following  the  #elif  directive  appear  in  the  output 
only  if  all  of  the  following  conditions  hold: 

•  The  constant-expression  in  the  preceding  #if  directive  evaluated  to  zero,  the  name  in 
the  preceding  #ifdef  is  not  defined,  or  the  name  in  the  preceding  #ifndef  directive 
was  defined. 

•  The  constant-expression  in  all  intervening  #elif  directives  evaluated  to  zero. 

•  The  current  constant-expression  evaluates  to  non-zero. 

If  the  constant-expression  evaluates  to  non-zero,  subsequent  #elif  and  #else  directives  are  ignored 
up  to  the  matching  #endif.  Any  constant-expression  allowed  in  an  #if  directive  is  allowed  in  an 
#elif  directive. 

#else  This  inverts  the  sense  of  the  conditional  directive  otherwise  in  effect.  If  the  preceding  conditional 
would  indicate  that  lines  are  to  be  included,  then  lines  between  the  #else  and  the  matching  #endif 
are  ignored.  If  the  preceding  conditional  indicates  that  lines  would  be  ignored,  subsequent  lines 
are  included  in  the  output.  Conditional  directives  and  corresponding  #els€  directives  can  be 
nested. 

#endif  End  a  section  of  lines  begun  by  one  of  the  conditional  directives  #if,  #ifdef,  or  #ifndef.  Each  such 
directive  must  have  a  matching  #endif. 

Macros 

Formal  parameters  for  macros  are  recognized  in  #define  directive  bodies,  even  when  they  occur  inside 
character  constants  and  quoted  strings.  For  instance,  the  output  from: 

#define  abc(a)  |\a| 
abc(xyz) 
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is  the  seven  characters  |  ‘xyz  |”  (SPACE,  vertical-bar,  backquote,  x.  y,  z,  vertical-bar).  Macro  names  are 
not  recognized  within  character  constants  or  quoted  strings  during  the  regular  scan.  Thus: 

#defineabc  xyz 
printf("abc"); 

does  not  expand  abc  in  the  second  line,  since  it  is  inside  a  quoted  string  that  is  not  part  of  a  #define  macro 
definition. 

Macros  are  not  expanded  while  processing  a  #define  or#und€f.  Thus: 

#define  abc  zingo 
#define  xyz  abc 
#undef  abc 
xyz 

produces  abc.  The  token  appearing  immediately  after  an  #ifdef  or  #ifndef  is  not  expanded. 

Macros  are  not  expanded  during  the  scan  which  determines  the  actual  parameters  to  another  macro  call. 
Thus: 


#define  reverse(first,second)second  first 
#define  greeting  hello 
reverse(greeting, 

#define  greeting  goodbye 

) 

produces  “  #define  hello  goodbye  hello”. 

Output 

Output  consists  of  a  copy  of  the  input  file,  with  modifications,  plus  lines  of  the  form: 

Mneno  ''filename^'  ''level" 

indicating  the  original  source  line  number  and  filename  of  the  following  output  line  and  whether  this  is  the 
first  such  line  after  an  include  file  has  been  entered  {level=l),  the  first  such  line  after  an  include  file  has 
been  exited  (level=2\  or  any  other  such  line  (level  is  empty). 

Details 

Directory  Search  Order 
#inc]ude  files  is: 

1.  The  directory  of  the  file  that  contains  the  #include  request  (that  is,  #include  is  relative  to  the 
file  being  scanned  when  the  request  is  made). 

2.  The  directories  specified  by  -I  options,  in  left-lo-right  order. 

3.  The  standard  directory(s)  (/usr/include  on  UNIX  systems). 

Special  Names 

Two  special  names  are  understood  by  cpp.  The  name  _  _LINE_  _  is  defined  as  the  current  line  number  (a 
decimal  integer)  as  known  by  cpp,  and  _  _FILE_  _  is  defined  as  the  current  filename  (a  C  string)  as  known 
by  cpp.  They  can  be  used  anywhere  (including  in  macros)  just  as  any  other  defined  name. 

Newline  Characters 

A  NEWLINE  character  terminates  a  character  constant  or  quoted  string.  An  escaped  NEWLINE  (that  is,  a 
backslash  immediately  followed  by  a  NEWLINE)  may  be  used  in  the  body  of  a  #define  statement  to  con¬ 
tinue  the  definition  onto  the  next  line.  The  escaped  NEWLINE  is  not  included  in  the  macro  value. 

Comments 

Comments  are  removed  (unless  the  -C  option  is  used  on  the  command  line).  Comments  are  also  ignored, 
except  that  a  comment  terminates  a  token. 
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SEE  ALSO 

cc(lV),  m4(lV) 

Programming  Utilities  and  Libraries 
DIAGNOSTICS 

The  error  messages  produced  by  cpp  are  intended  to  be  self-explanatory.  The  line  number  and  filename 
where  the  error  occurred  are  printed  along  with  the  diagnostic. 

NOTES 

When  NEWLINE  characters  were  found  in  argument  lists  for  macros  to  be  expanded,  sc^e  previous  ver¬ 
sions  of  cpp  put  out  the  NEWLINE  characters  as  they  were  found  and  expanded.  The  current  version  of 
cpp  replaces  diem  with  SPACE  characters. 

Because  the  standard  directory  for  included  files  may  be  different  in  different  environments,  this  form  of 
#include  directive: 

#inc]ude  <file.h> 

should  be  used,  rather  than  one  with  an  absolute  path,  like: 

#in€lude  '7usr/include/file.h^' 
cpp  warns  about  the  use  of  the  absolute  pathname. 

While  the  compiler  allows  8-bit  strings  and  comments,  8-bits  are  not  allowed  anywhere  else.  See  cc(lV) 
for  an  explanation  about  why  cc  is  not  8-bit  clean. 
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NAME 

crontab  -  install,  edit,  remove  or  list  a  user’s  crontab  file 

SYNOPSIS 

crontab  [filename  ] 
crontab  [  username  ] 
crontab  -1  [  username  ] 
crontab  -r  [  username  ] 

DESCRIPTION 

crontab  copies  the  specified  file,  or  the  standard  input  if  no  file  is  specified,  into  a  directory  that  holds  all 
users’  crontab  files,  A  user’s  crontab  file  lists  commands  that  are  to  be  executed  on  behalf  of  that  user  at 
specified  times  on  specified  dates;  the  format  of  these  files  is  described  in  crontab(5). 

If  the  file  /var/spooI/cron/cron.alIow  exists,  only  users  whose  username  appears  in  it  can  use  crontab.  If 
that  file  does  not  exist,  however,  crontab  checks  the  /var/spool/cron/cron.deny  file  to  determine  if  the 
user  should  be  denied  the  use  of  crontab.  If  neither  file  exists,  only  the  super-user  is  allowed  to  submit  a 
crontab  job.  If  cron.alIow  does  not  exist  and  cron.deny  exists  and  is  empty,  global  usage  is  permitted. 
The  allow/deny  files  consist  of  one  user  name  per  line, 

OPTIONS 

-e  Make  a  copy  of  the  current  user’s  crontab  file,  or  create  an  empty  file  if  it  does  not  exist,  and  edit 
that  file.  The  vi(l)  editor  will  be  used  unless  the  environment  variable  VISUAL  or  EDITOR  indi¬ 
cates  an  alternate  editor.  When  editing  is  complete,  install  the  file  as  the  user’s  crontab  file  if  it 
was  modified.  If  a  username  is  given,  the  specified  user’s  crontab  file  is  edited,  rather  than  the 
current  user’s  crontab  file;  this  may  only  be  done  by  the  super-user. 

-I  List  the  user’s  crontab  file. 

-r  Remove  the  current  user’s  crontab  file  from  the  crontab  directory.  If  a  username  is  given,  the 
specified  user’s  crontab  file  is  removed,  rather  than  the  current  user’s  crontab  file;  this  may  only 
be  done  by  the  super-user. 


FILES 

/var/spool/cron 
/var/spool/cron/crontabs 
/var/spool/cron/cron, allow 
/var/spool/cron/cron.deny 


main  cron  directory 
spool  area 
list  of  allowed  users 
list  of  denied  users 


SEE  ALSO 

sh(l),  crontab(5),  cron(8) 


WARNINGS 

If  you  inadvertently  enter  the  crontab  command  with  no  argument,  do  not  attempt  to  get  out  by  typing 
CTRL-D.  This  removes  all  entries  in  your  crontab  file.  Instead,  exit  by  typing  your  interrupt  character 
(normally  CTRL-C). 
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NAME 

crypt  -  encode  or  decode  a  file 

SYNOPSIS 

crypt  [  password  ] 

DESCRIPTION 

crypt  encrypts  and  decrypts  the  contents  of  a  file,  crypt  reads  from  the  standard  input  and  writes  on  the 
standard  output.  The  password  is  a  key  that  selects  a  particular  transformation.  If  no  password  is  given, 
crypt  demands  a  key  from  the  terminal  and  turns  off  printing  while  the  key  is  being  typed  in.  crypt 
encrypts  and  decrypts  with  the  same  key: 

example  %  crypt  key  <  clear,  file  >  encrypted,  file 
example%  < encrypted. file  \  pr 

will  print  the  contents  of  clear. file. 

Files  encrypted  by  crypt  are  compatible  with  those  treated  by  the  editors  ed(l),  ex(l)  and  vi(l)  in  encryp¬ 
tion  mode. 

The  security  of  encrypted  files  depends  on  three  factors:  the  fundamental  method  must  be  hard  to  solve; 
direct  search  of  the  key  space  must  be  infeasible;  “sneak  paths”  by  which  keys  or  cleartext  can  become 
visible  must  be  minimized. 

crypt  implements  a  one-rotor  machine  designed  along  the  lines  of  the  German  Enigma,  but  with  a  256- 
element  rotor.  Methods  of  attack  on  such  machines  are  widely  known,  thus  crypt  provides  minimal  secu¬ 
rity. 

The  transformation  of  a  key  into  the  internal  settings  of  the  machine  is  deliberately  designed  to  be  expen¬ 
sive,  that  is,  to  take  a  substantial  fraction  of  a  second  to  compute.  However,  if  keys  are  restricted  to  (say) 
three  lower-case  letters,  then  encrypted  files  can  be  read  by  expending  only  a  substantial  fraction  of  five 
minutes  of  machine  time. 

Since  the  key  is  an  argument  to  the  crypt  command,  it  is  potentially  visible  to  users  executing  ps(l)  or  a 
derivative  command.  To  minimize  this  possibility,  crypt  takes  care  to  destroy  any  record  of  the  key 
immediately  upon  entry.  No  doubt  the  choice  of  keys  and  key  security  are  the  most  vulnerable  aspect  of 

crypt. 

FILES 

/dev/tty  for  typed  key 

SEE  ALSO 

des(l),  ed(l),  ex(l),  ps(l),  vi(l),  makekey(8) 

RESTRICTIONS 

This  program  is  not  available  on  software  shipped  outside  the  U.S, 
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NAME 

csh  “  a  shell  (command  interpreter)  with  a  C-like  syntax  and  advanced  interactive  features 
SYNOPSIS 

csh  [  -bcefinstvVxX  ]  [  argument. . .  ] 

DESCRIPTION 

csh,  the  C  shell,  is  a  command  interpreter  with  a  syntax  reminiscent  of  C.  It  provides  a  number  of  con¬ 
venient  features  for  interactive  use  that  are  not  available  with  the  standard  (Bourne)  shell,  including 
filename  completion,  command  aliasing,  history  substitution,  job  control,  and  a  number  of  built-in  com¬ 
mands.  As  with  the  standard  shell,  the  C  shell  provides  variable,  command  and  filename  substitution. 

Initialization  and  Termination 

When  first  started,  the  C  shell  normally  performs  commands  from  the  xshrc  file  in  your  home  directory, 
provided  that  it  is  readable  and  you  either  own  it  or  your  real  group  ID  matches  its  group  ID.  If  the  shell  is 
invoked  with  a  name  that  starts  with  as  when  started  by  login(l),  the  shell  runs  as  a  login  shell.  In  this 
case,  after  executing  commands  from  the  .cshrc  file,  the  shell  executes  commands  from  the  .login  file  in 
your  home  directory;  the  same  permission  checks  as  those  for  .cshrc  are  applied  to  this  file.  Typically,  the 
.login  file  contains  commands  to  specify  the  terminal  type  and  environment. 

As  a  login  shell  terminates,  it  performs  commands  from  the  .logout  file  in  your  home  directory;  the  same 
permission  checks  as  those  for  .cshrc  are  applied  to  this  file. 

Interactive  Operation 

After  startup  processing  is  complete,  an  interactive  C  shell  begins  reading  commands  from  the  terminal, 
prompting  with  hostname  %  (or  hostname^  for  the  super-user).  The  shell  then  repeatedly  performs  the  fol¬ 
lowing  actions:  a  line  of  command  input  is  read  and  broken  into  words.  This  sequence  of  words  is  placed 
on  the  history  list  and  then  parsed,  as  described  under  USAGE,  below.  Finally,  the  shell  executes  each 
command  in  the  current  line. 

Noninteractive  Operation 

When  running  noninteractively,  the  shell  does  not  prompt  for  input  from  the  terminal.  A  noninteractive  C 
shell  can  execute  a  command  supplied  as  an  argument  on  its  command  line,  or  interpret  commands  from  a 
script. 

OPTIONS 

-b  Force  a  “break”  from  option  processing.  Subsequent  command-line  arguments  are  not  interpreted 
as  C  shell  options.  This  allows  the  passing  of  options  to  a  script  without  confusion.  The  shell 
does  not  run  a  set-user-ID  script  unless  this  option  is  present. 

— c  Read  commands  from  the  first  filename  argument  (which  must  be  present).  Remaining  arguments 
are  placed  in  argv,  the  argument-list  variable. 

— e  Exit  if  a  command  terminates  abnormally  or  yields  a  nonzero  exit  status. 

-f  Fast  start.  Read  neither  the  .cshrc  file,  nor  the  .login  file  (if  a  login  shell)  upon  startup. 

-i  Forced  interactive.  Prompt  for  command-line  input,  even  if  the  standard  input  does  not  appear  to 

be  a  terminal  (character-special  device). 

-n  Parse  (interpret),  but  do  not  execute  commands.  This  option  can  be  used  to  check  C  shell  scripts 
for  syntax  errors. 

-s  Take  commands  from  the  standard  input. 

-t  Read  and  execute  a  single  command  line.  A  ‘\’  (backslash)  can  be  used  to  escape  each  NEWLINE 
for  continuation  of  the  command  line  onto  subsequent  input  lines. 

“V  Verbose.  Set  the  verbose  predefined  variable;  command  input  is  echoed  after  history  substitution 
(but  before  other  substitutions)  and  before  execution. 

-V  Set  verbose  before  reading  .cshrc. 
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-X  Echo.  Set  the  echo  variable;  echo  commands  after  all  substitutions  and  just  before  execution. 

~X  Set  echo  before  reading  .cshrc. 

Except  with  the  options  — c,  — i,  — s  or  — t,  the  first  nonoption  argument  is  taken  to  be  the  name  of  a  command 
or  script.  It  is  passed  as  argument  zero,  and  subsequent  arguments  are  added  to  the  argument  list  for  that 
command  or  script. 

USAGE 

Refer  to  SunOS  User's  Guide:  Doing  More  for  tutorial  information  on  how  to  use  the  various  features  of 
the  C  shell. 

Filename  Completion 

When  enabled  by  setting  the  variable  filec,  an  interactive  C  shell  can  complete  a  partially  typed  filename  or 
user  name.  When  an  unambiguous  partial  filename  is  followed  by  an  ESC  character  on  the  terminal  input 
line,  the  shell  fills  in  the  remaining  characters  of  a  matching  filename  from  the  working  directory. 

If  a  partial  filename  is  followed  by  the  EOF  character  (usually  typed  as  CTRL-D),  the  shell  lists  all  filenames 
that  match.  It  then  prompts  once  again,  supplying  the  incomplete  command  line  typed  in  so  far. 

When  the  last  (partial)  word  begins  with  a  tilde  (~),  the  shell  attempts  completion  with  a  user  name,  rather 
than  a  file  in  the  working  directory. 

The  terminal  bell  signals  errors  or  multiple  matches;  this  can  be  inhibited  by  setting  the  variable  nobeep. 
You  can  exclude  files  with  certain  suffixes  by  listing  those  suffixes  in  the  variable  fignore.  If,  however,  the 
only  possible  completion  includes  a  suffix  in  the  list,  it  is  not  ignored,  fignore  does  not  affect  the  listing  of 
filenames  by  the  EOF  character. 

Lexical  Structure 

The  shell  splits  input  lines  into  words  at  SPACE  and  TAB  charactCTS,  except  as  noted  below.  The  characters 
&T  I, <,  >,  (,  and  )  form  separate  words;  if  paired,  the  pairs  form  single  words.  These  shell  metacharac¬ 
ters  can  be  made  part  of  other  words,  and  their  special  meaning  can  be  suppressed  by  preceding  them  with 
a  ‘\’  (backslash).  A  NEWLINE  preceded  by  a  \  is  equivalent  to  a  SPACE  character. 

In  addition,  a  string  enclosed  in  matched  pairs  of  single-quotes  ( '),  double-quotes  ( " ),  or  backquotes  (' ), 
forms  a  partial  word;  metacharacters  in  such  a  string,  including  any  SPACE  or  TAB  characters,  do  not  form 
separate  words.  Within  pairs  of  backquote  (' )  or  double-quote  ( " )  characters,  a  NEWLINE  preceded  by  a 
‘\’  (backslash)  gives  a  true  NEWLINE  character.  Addition^  functions  of  each  type  of  quote  are  described, 
below,  under  Variable  Substitution,  Command  Substitution,  and  Filename  Substitution. 

When  the  shelTs  input  is  not  a  terminal,  the  character  #  introduces  a  comment  that  continues  to  the  end  of 
the  input  line.  Its  special  meaning  is  suppressed  when  preceded  by  a  \  or  enclosed  in  matching  quotes. 

Command  Line  Parsing 

A  simple  command  is  composed  of  a  sequence  of  words.  The  first  word  (that  is  not  part  of  an  I/O  redirec¬ 
tion)  specifies  the  command  to  be  executed.  A  simple  command,  or  a  set  of  simple  commands  separated  by 
I  or  |&  characters,  forms  a  pipeline.  With  |,  the  standard  output  of  the  preceding  command  is  redirected  to 
the  standard  input  of  the  command  that  follows.  With  j  &  ,  both  the  standard  error  and  the  standard  output 
are  redirected  through  the  pipeline. 

Pipelines  can  be  separated  by  semicolons  ( ; ),  in  which  case  they  are  executed  sequentially.  Pipelines  that 
are  separated  by  &&  or  1 1  form  conditional  sequences  in  which  the  execution  of  pipelines  on  the  right 
depends  upon  the  success  or  failure,  respectively,  of  the  pipeline  on  the  left. 

A  pipeline  or  sequence  can  be  enclosed  within  parentheses  ‘O’  to  form  a  simple  command  that  can  be  a 
component  in  a  pipeline  or  sequence. 

A  sequence  of  pipelines  can  be  executed  asynchronously,  or  “in  the  background”  by  appending  an  *&’; 
rather  than  waiting  for  the  sequence  to  finish  before  issuing  a  prompt,  the  shell  displays  the  job  number 
(see  Job  Control,  below)  and  associated  process  IDs,  and  prompts  immediately. 
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History  Substitution 

History  substitution  allows  you  to  use  words  from  previous  command  lines  in  the  command  line  you  are 
typing.  This  simplifies  spelling  corrections  and  the  repetition  of  complicated  commands  or  arguments. 
Command  lines  are  saved  in  the  history  list,  the  size  of  which  is  controlled  by  the  history  variable.  The 
most  recent  command  is  retained  in  any  case.  A  history  substitution  begins  with  a  I  (although  you  can 
change  this  with  the  histchars  variable)  and  may  occur  anywhere  on  the  command  line;  history  substitu¬ 
tions  do  not  nest.  The  !  can  be  escaped  with  \  to  suppress  its  special  meaning. 

Input  lines  containing  history  substitutions  are  echoed  on  the  terminal  after  being  expanded,  but  before  any 
other  substitutions  take  place  or  the  command  gets  executed. 

Event  Designators 

An  event  designator  is  a  reference  to  a  command-line  entry  in  the  history  list 

!  Start  a  history  substitution,  except  when  followed  by  a  SPACE  character,  TAB,  NEWLINE, 

=  or  (. 

1!  Refer  to  the  previous  command.  By  itself,  this  substitution  repeats  the  previous  com¬ 
mand. 

!  n  Refer  to  command-line  n . 

l-n  Refer  to  the  current  command-line  minus  n. 

Istr  Refer  to  the  most  recent  command  starting  with  str. 

l?str[?]  Refer  to  the  most  recent  command  containing  sir. 

!{...}  Insulate  a  history  reference  from  adjacent  characters  (if  necessary). 

Word  Designators 

A  (colon)  separates  the  event  specification  from  the  word  designator.  It  can  be  omitted  if  the  word 
designator  begins  with  a  or  %.  If  the  word  is  to  be  selected  from  the  previous  command,  the 

second  !  character  can  be  omitted  from  the  event  specification.  For  instance,  V.:l  and  !:1  both  refer  to  the 
first  word  of  the  previous  command,  while  !!$  and  !$  both  refer  to  the  last  word  in  the  previous  command. 
Word  designators  include: 

#  The  entire  command  line  typed  so  far. 

0  The  first  input  word  (command). 

n  The  n  ’ th  argument. 

^  The  first  argument,  that  is,  1. 

$  The  last  argument. 

%  The  word  matched  by  (the  most  recent)  search. 

x-y  A  range  of  words;  -y  abbreviates  0-y. 

*  All  the  arguments,  or  a  null  value  if  there  is  just  one  word  in  the  event. 

X*  Abbreviates  x-$. 

X-  Like  jc*  but  omitting  word  $. 

Modifiers 

After  the  optional  word  designator,  you  can  add  a  sequence  of  one  or  more  of  the  following  modifiers,  each 
preceded  by  a 

h  Remove  a  trailing  pathname  component,  leaving  the  head, 
r  Remove  a  trailing  suffix  of  the  form  'jooc\  leaving  the  basename. 
e  Remove  all  but  the  suffix, 

s///r[/]  Substitute  r  for  / . 

t  Remove  all  leading  pathname  components,  leaving  the  tail. 

&  Repeat  the  previous  substitution. 

g  Apply  the  change  to  the  first  occurrence  of  a  match  in  each  word,  by  prefixing  the  above 
(for  example,  g&). 

p  Print  the  new  command  but  do  not  execute  it. 
q  Quote  the  substituted  words,  escaping  further  substitutions. 

X  Like  q,  but  break  into  words  at  each  SPACE  character,  TAB  or  NEWLINE. 
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Unless  preceded  by  a  g,  the  modification  is  applied  only  to  the  first  string  that  matches  l\  an  error  results  if 
no  string  matches. 

The  left-hand  side  of  substitutions  are  not  regular  expressions,  but  character  strings.  Any  character  can  be 
used  as  the  delimiter  in  place  of  /.  A  backslash  quotes  the  delimiter  character.  The  character  &,  in  the 
right  hand  side,  is  replaced  by  the  text  from  the  left-hand-side.  The  &  can  be  quoted  with  a  backslash.  A 
null  I  uses  the  previous  string  either  from  a  I  or  from  a  contextual  scan  string  s  from  11  s.  You  can  omit  the 
rightmost  delimiter  if  a  NEWLINE  immediately  follows  r;  the  rightmost  ?  in  a  context  scan  can  similarly  be 
omitted. 

Without  an  event  specification,  a  history  reference  refers  either  to  the  previous  command,  or  to  a  previous 
history  reference  on  the  command  line  (if  any). 

Quick  Substitution 

This  is  equivalent  to  the  history  substitution: 

Aliases 

The  C  shell  maintains  a  list  of  aliases  that  you  can  create,  display,  and  modify  using  the  alias  and  unalias 
commands.  The  shell  checks  the  first  word  in  each  command  to  see  if  it  matches  the  name  of  an  existing 
alias.  If  it  does,  the  command  is  reprocessed  with  the  alias  definition  replacing  its  name;  the  history  substi¬ 
tution  mechanism  is  made  available  as  though  that  command  were  the  previous  input  line.  This  allows  his¬ 
tory  substitutions,  escaped  with  a  backslash  in  the  definition,  to  be  replaced  with  actual  command-line 
arguments  when  the  alias  is  used.  If  no  history  substitution  is  called  for,  the  arguments  remain  unchanged. 

Aliases  can  be  nested.  That  is,  an  alias  definition  can  contain  the  name  of  another  alias.  Nested  aliases  are 
expanded  before  any  history  substitutions  is  applied.  This  is  useful  in  pipelines  such  as 

alias  Im  'Is  -1  \!*  |  more' 

which  when  called,  pipes  the  output  of  Is(lV)  through  more(l). 

Except  for  the  first  word,  the  name  of  the  alias  may  not  appear  in  its  definition,  nor  in  any  alias  referred  to 
by  its  definition.  Such  loops  are  detected,  and  cause  an  error  message. 

I/O  Redirection 

The  following  metacharacters  indicate  that  the  subsequent  word  is  the  name  of  a  file  to  which  the 
command’s  standard  input,  standard  output,  or  standard  error  is  redirected;  this  word  is  variable,  command, 
and  filename  expanded  separately  from  the  rest  of  the  command. 

<  Redirect  the  standard  input. 

<  <  word  Read  the  standard  input,  up  to  a  line  that  is  identical  with  word,  and  place  the  resulting 

lines  in  a  temporary  file.  Unless  word  is  escaped  or  quoted,  variable  and  command  sub¬ 
stitutions  are  performed  on  these  lines.  Then,  invoke  the  pipeline  with  the  temporary  file 
as  its  standard  input,  word  is  not  subjected  to  variable,  filename  or  command  substitu¬ 
tion,  and  each  line  is  compared  to  it  before  any  substitutions  are  performed  by  the  shell. 

>  >!  >&  >&!  Redirect  the  standard  output  to  a  file.  If  the  file  does  not  exist,  it  is  created.  If  it  does 
exist,  it  is  overwritten;  its  previous  contents  are  lost. 

When  set,  the  variable  noclobber  prevents  destruction  of  existing  files.  It  also  prevents 
redirection  to  terminals  and  /dev/null,  unless  one  of  the  !  forms  is  used.  The  &  forms 
redirect  both  standard  output  and  the  standard  error  (diagnostic  output)  to  the  file. 

>>  >>&  >>!  >>&! 

Append  the  standard  output.  Like  >,  but  places  output  at  the  end  of  the  file  rather  than 
overwriting  it.  If  noclobber  is  set,  it  is  an  error  for  the  file  not  to  exist,  unless  one  of  the 
!  forms  is  used.  The  &  forms  append  both  the  standard  error  and  standard  output  to  the 
file. 
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Variable  Substitution 

The  C  shell  inaintains  a  set  of  variables ^  each  of  which  is  composed  of  a  name  and  a  value.  A  variable 
name  consists  of  up  to  20  letters  and  digits,  and  starts  with  a  letter  (the  underscore  is  considered  a  letter). 
A  variable’s  value  is  a  space-separated  list  of  zero  or  more  words. 

To  refer  to  a  variable’s  value,  precede  its  name  with  a  '$’.  Certain  references  (described  below)  can  be 
used  to  select  specific  words  from  the  value,  or  to  display  other  information  about  the  variable.  Braces  can 
be  used  to  insulate  the  reference  from  other  characters  in  an  input-line  word. 

Variable  substitution  takes  place  after  the  input  line  is  analyzed,  aliases  are  resolved,  and  I/O  redirections 
are  applied.  Exceptions  to  this  are  variable  references  in  I/O  redirections  (substituted  at  the  time  the 
redirection  is  made),  and  backquoted  strings  (see  Command  Substitution). 

Variable  substitution  can  be  suppressed  by  preceding  the  $  with  a  \,  except  within  double-quotes  where  it 
always  occurs.  Variable  substitution  is  suppressed  inside  of  single-quotes.  A  $  is  escaped  if  followed  by  a 
SPACE  character,  TAB  or  NEWUNE. 


Variables  can  be  created,  displayed,  or  destroyed  ising  the  set  and  unset  commands.  Some  variables  are 
maintained  or  used  by  the  shell.  For  instance,  the  argv  variable  contains  an  image  of  the  shell’s  argument 
list.  Of  the  variables  used  by  the  shell,  a  number  are  toggles;  the  shell  does  not  care  what  their  value  is, 
only  whether  they  are  set  or  not. 


Numerical  values  can  be  operated  on  as  numbers  (as  with  the  @  built-in).  With  numeric  operations,  an 
empty  value  is  considered  to  be  zero;  the  second  and  subsequent  words  of  multiword  values  are  ignored. 
For  instance,  when  the  verbose  variable  is  set  to  any  value  (including  an  empty  value),  command  input  is 
echoed  on  the  terminal. 


Command  and  filename  substitution  is  subsequently  applied  to  the  words  that  result  from  the  variable  sub¬ 
stitution,  except  when  suppressed  by  double-quotes,  when  noglob  is  set  (suppressing  filename  substitu¬ 
tion),  or  when  the  reference  is  quoted  with  the  :q  modifier.  Within  double-quotes,  a  reference  is  expanded 
to  form  (a  portion  of)  a  quoted  string;  multiword  values  are  expanded  to  a  string  with  embedded  SPACE 
characters.  When  the  :q  modifier  is  applied  to  the  reference,  it  is  expanded  to  a  list  of  space-separated 
words,  each  of  which  is  quoted  to  prevent  subsequent  command  or  filename  substitutions. 

Except  as  noted  below,  it  is  an  error  to  refer  to  a  variable  that  is  not  set. 


$var 


%var  [index] 
${var[index]} 


$ttname 

${#name} 


These  are  replaced  by  words  from  the  value  of  var,  each  separated  by  a  SPACE  charac¬ 
ter.  If  var  is  an  environment  variable,  its  value  is  returned  (but  modifiers  and  the 
other  forms  given  below  are  not  available). 


These  select  only  the  indicated  words  from  the  value  of  var.  Variable  substitution  is 
applied  to  index ,  which  may  consist  of  (or  result  in)  a  either  single  number,  two 
numbers  separated  by  a  or  an  asterisk.  Words  are  indexed  starting  from  1;  a 
selects  all  words.  If  the  first  number  of  a  range  is  omitted  (as  with  $argv[-2]),  it 
defaults  to  1.  If  the  last  number  of  a  range  is  omitted  (as  with  $argv[l-]),  it  defaults  to 
$ttvar  (the  word  count).  It  is  not  an  error  for  a  range  to  be  empty  if  the  second  argument 
is  omitted  (or  within  range). 

These  give  the  number  of  words  in  the  variable. 


$0 


This  substitutes  the  name  of  the  file  from  which  command  input  is  being  read.  An  error 
occurs  if  the  name  is  not  known. 
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%n 

${/» }  Equivalent  to  $argv[n  ] . 

$*  Equivalent  to  $argv[*]. 

The  modifiers  :e,  :h,  :q,  :r,  :t  and  :x  can  be  applied  (see  History  Substitution),  as  can  :gh,  :gt  and  :gr.  If 
{}  (braces)  are  used,  then  the  modifiers  must  appear  within  the  braces.  The  current  implementation  allows 
only  one  such  modifier  per  expansion. 

The  following  references  may  not  be  modified  with :  modifiers. 

%7var 

${?vflr}  Substitutes  the  string  1  if  yar  is  set  or  0  if  it  is  not  set. 

$?0  Substitutes  1  if  the  current  input  filename  is  known,  or  0  if  it  is  not. 

$$  Substitute  the  process  number  of  the  (parent)  shell. 

$<  Substitutes  a  line  from  the  standard  input,  with  no  further  interpretation  thereafter.  It  can  be  used 
to  read  fi'om  the  keyboard  in  a  C  shell  script. 

Command  and  Filename  Substitutions 

Command  and  filename  substitutions  are  applied  selectively  to  the  arguments  of  built-in  commands.  Por¬ 
tions  of  expressions  that  are  not  evaluated  are  not  expanded  For  non-built-in  commands,  filename  expan¬ 
sion  of  the  command  name  is  done  separately  from  that  of  the  argument  list;  expansion  occurs  in  a  sub¬ 
shell,  after  I/O  redirection  is  performed. 

Command  Substitution 

A  command  enclosed  by  backquotes  ('...')  is  performed  by  a  subshell.  Its  standard  output  is  broken  into 
separate  words  at  each  SPACE  character,  TAB  and  NEWLINE;  null  words  are  discarded.  This  text  replaces 
the  backquoted  string  on  the  current  command  line.  Within  double-quotes,  only  NEWLINE  characters  force 
new  words;  SPACE  and  TAB  characters  are  preserved.  However,  a  final  NEWLINE  is  ignored.  It  is  there¬ 
fore  possible  for  a  command  substitution  to  yield  a  partial  word. 

Filename  Substitution 

Unquoted  words  containing  any  of  the  characters  *,  ?,  [  or  {,  or  that  begin  with  are  expanded  (also 
known  as  globbing)  to  an  alphabetically  sorted  list  of  filenames,  as  follows: 

*  Match  any  (zero  or  more)  characters. 

?  Match  any  single  character. 

[ . . .  ]  Match  any  single  character  in  the  enclosed  list(s)  or  range(s),  A  list  is  a  string  of  charac¬ 

ters.  A  range  is  two  characters  separated  by  a  minus-sign  (-),  and  includes  all  the  char¬ 
acters  in  between  in  the  ASCII  collating  sequence  (see  ascii(7)). 

{  str,  str,...  } 

Expand  to  each  string  (or  filename-matching  pattern)  in  the  comma-separated  list. 
Unlike  the  pattern-matching  expressions  above,  the  expansion  of  this  construct  is  not 
sorted.  For  instance,  {b,a}  expands  to  ‘b’  ‘a\  (not  ‘a*  *b’).  As  special  cases,  the  char¬ 
acters  {  and  },  along  with  the  string  {  },  are  passed  undisturbed. 

[  user  ]  Your  home  directory,  as  indicated  by  the  value  of  the  variable  home,  or  that  of 

user^  as  indicated  by  the  password  entry  for  user. 

Only  the  patterns  ♦,  ?  and  [. , .]  imply  pattern  matching;  an  error  results  if  no  filename  matches  a  pattern 
that  contains  them.  The  (dot  character),  when  it  is  the  first  character  in  a  filename  or  pathname  com¬ 
ponent,  must  be  matched  explicitly.  The  /  (slash)  must  also  be  matched  explicitly. 

Expressions  and  Operators 

A  number  of  C  shell  built-in  commands  accept  expressions,  in  which  the  operators  are  similar  to  those  of  C 
and  have  the  same  precedence.  These  expressions  typically  appear  in  the  @,  exit,  if,  set  and  while  com¬ 
mands,  and  are  often  used  to  regulate  the  flow  of  control  for  executing  commands.  Components  of  an 
expression  are  separated  by  white  space. 
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Null  or  missing  values  are  considered  0.  The  result  of  all  expressions  are  strings,  which  may  represent 
decimal  numbers. 


The  following  C  shell  operators  are  grouped  in  order  of  precedence: 


(...) 

grouping 

one*s  complement 

! 

logical  negation 

*  /  % 

multiplication,  division,  remainder  (These  are  right  associative,  which 
can  lead  to  unexpected  results.  Group  combinations  explicitly  with 
parentheses.) 

+  - 

addition,  subtraction  (also  right  associative) 

«  » 

bitwise  shift  left,  bitwise  shift  right 

X 

II 

V 

A 

V 

less  than,  greater  than,  less  than  or  equal  to,  greater  than  or  equal  to 

—  —  J—  J 

equal  to,  not  equal  to,  filename-substitution  pattern  match  (described 
below),  filename-substitution  pattern  mismatch 

& 

bitwise  AND 

bitwise  XOR  (exclusive  or) 

1 

bitwise  inclusive  OR 

&& 

logical  AND 

II 

logical  OR 

The  operators:  ==,  !=,  =-, 

and  compare  their  arguments  as  strings;  other  operators  use  numbers.  The 

operators  =~  and  each  check  whether  or  not  a  string  to  the  left  matches  a  filename  substitution  pattern 
on  the  right.  This  reduces  the  need  for  switch  statements  when  pattern-matching  between  strings  is  all  that 
is  required. 

Also  available  are  file  inquiries: 

-r  filename  Return  true,  or  1  if  the  user  has  read  access.  Otherwise  it  returns  false,  or  0. 

“W  filename 

True  if  the  user  has  write  access. 

-X  filename 

True  if  the  user  has  execute  permission  (or  search  permission  on  a  directory). 

-e  filename  True  if  file  exists. 

-o  filename 

True  if  the  user  owns  file, 

-I.  filename  True  if  file  is  of  zero  length  (empty). 

~f  filename  True  if  file  is  a  plain  file. 

-d  filename 

True  if  file  is  a  directory. 

If  file  does  not  exist  or  is  inaccessible,  then  all  inquiries  return  false. 

An  inquiry  as  to  the  success  of  a  command  is  also  available: 

{  command  } 

If  command  runs  successfully,  the  expression  evaluates  to  true,  1.  Otherwise  it  evalu¬ 
ates  to  false  0.  (Note  that,  conversely,  command  itself  typically  returns  0  when  it  runs 
successfully,  or  some  other  value  if  it  encounters  a  problem.  If  you  want  to  get  at  the 
status  directly,  use  the  value  of  the  status  variable  rather  than  this  expression). 

Control  Flow 

The  shell  contains  a  number  of  commands  to  regulate  the  flow  of  control  in  scripts,  and  within  limits,  from 
the  terminal.  These  commands  operate  by  forcing  the  shell  either  to  reread  input  (to  loop),  or  to  skip  input 
under  certain  conditions  (to  branch). 

Each  occurrence  of  a  foreach,  switch,  while,  if. .  .then  and  else  built-in  must  appear  as  the  first  word  on  its 
own  input  line. 
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If  the  shell’s  input  is  not  seekable  and  a  loop  is  being  read,  that  input  is  buffered.  The  shell  performs  seeks 
within  the  internal  buffer  to  accomplish  the  rereading  implied  by  the  loop.  (To  the  extent  that  this  allows, 
backward  goto  commands  will  succeed  on  nonseekable  inputs.) 

Command  Execution 

If  the  command  is  a  C  shell  built-in,  the  shell  executes  it  directly.  Otherwise,  the  shell  searches  for  a  file  by 
that  name  with  execute  access.  If  the  command-name  contains  a  /,  the  shell  takes  it  as  a  pathname,  and 
searches  for  it.  If  the  command-name  does  not  contain  a  /,  the  shell  attempts  to  resolve  it  to  a  pathname, 
searching  each  directory  in  the  path  variable  for  the  command.  To  speed  the  search,  the  shell  uses  its  hash 
table  (see  the  rehash  built-in)  to  eliminate  directories  that  have  no  applicable  files.  This  hashing  can  be 
disabled  with  the  -c  or  -t,  options,  or  the  unhash  built-in. 

As  a  special  case,  if  there  is  no  /  in  the  name  of  the  script  and  there  is  an  alias  for  the  word  shell,  the  expan¬ 
sion  of  the  shell  alias  is  prepended  (without  modification),  to  the  command  line.  The  system  attempts  to 
execute  the  first  word  of  this  special  (late-occurring)  alias,  which  should  be  a  full  pathname.  Remaining 
words  of  the  alias’s  definition,  along  with  the  text  of  the  input  line,  are  treated  as  arguments. 

When  a  pathname  is  found  that  has  proper  execute  permissions,  the  shell  forks  a  new  process  and  passes  it, 
along  with  its  arguments  to  the  kernel  (using  the  execve(2V)  system  call).  The  kernel  then  attempts  to 
overlay  the  new  process  with  the  desired  program.  If  the  file  is  an  executable  binary  (in  a.out(5)  format) 
the  kernel  succeeds,  and  begins  executing  the  new  process.  If  the  file  is  a  text  file,  and  the  first  line  begins 
with  the  next  word  is  taken  to  be  the  pathname  of  a  shell  (or  command)  to  interpret  that  script.  Subse¬ 
quent  words  on  the  first  line  are  taken  as  options  for  that  shell.  The  kernel  invokes  (overlays)  the  indicated 
shell,  using  the  name  of  the  script  as  an  argument. 

If  neither  of  the  above  conditions  holds,  the  kernel  cannot  overlay  the  file  (the  execve(2V)  call  fails);  the  C 
shell  then  attempts  to  execute  the  file  by  spawning  a  new  shell,  as  follows: 

•  If  the  first  character  of  the  file  is  a  #,  a  C  shell  is  invoked. 

•  Otherwise,  a  standard  (Bourne)  shell  is  invoked. 

Signal  Handling 

The  shell  normally  ignores  QUIT  signals.  Background  jobs  are  immune  to  signals  generated  from  the  key¬ 
board,  including  hangups  (HUP).  Other  signals  have  the  values  that  the  C  shell  inherited  from  its  environ¬ 
ment.  The  shell’s  handling  of  interrupt  and  terminate  signals  within  scripts  can  be  controlled  by  the  onintr 
built-in.  Login  shells  catch  the  TERM  signal;  otherwise  this  signal  is  passed  on  to  child  processes.  In  no 
case  are  interrupts  allowed  when  a  login  shell  is  reading  the  .logout  file. 

Job  Control 

The  shell  associates  a  numbered  job  with  each  command  sequence,  to  keep  track  of  those  commands  that 
are  running  in  the  background  or  have  been  stopped  with  TSTP  signals  (typically  CTRL-Z).  When  a  com¬ 
mand,  or  command  sequence  (semicolon  separated  list),  is  started  in  the  background  using  the  &  metachar¬ 
acter,  the  shell  displays  a  line  with  the  job  number  in  brackets,  and  a  list  of  associated  process  numbers: 

[1]  1234 

To  see  the  current  list  of  jobs,  use  the  jobs  built-in  command.  The  job  most  recently  stopped  (or  put  into 
the  background  if  none  are  stopped)  is  referred  to  as  the  current  job,  and  is  indicated  with  a  ‘+’.  The  previ¬ 
ous  job  is  indicated  with  a  when  the  current  job  is  terminated  or  moved  to  the  foreground,  this  job 
takes  its  place  (becomes  the  new  current  job). 

To  manipulate  jobs,  refer  to  the  bg,  fg,  kill,  stop  and  %  built-ins. 

A  reference  to  a  job  begins  with  a  *%  ’.  By  itself,  the  percent-sign  refers  to  the  current  job. 

%  %+  %%  The  current  job. 

%-  The  previous  job. 

%j  Refer  to  job  j  as  in:  ‘kill  -9  %/,  j  can  be  a  job  number,  or  a  string  that  uniquely 

specifies  the  command-line  by  which  it  was  started;  ‘fg  %vi’  might  bring  a  stopped  vi 
job  to  the  foreground,  for  instance. 
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%lstring  Specify  the  job  for  which  the  command-line  uniquely  contains  string. 

A  job  running  in  the  background  stops  when  it  attempts  to  read  from  the  terminal.  Background  jobs  can 
normally  produce  output,  but  this  can  be  suppressed  using  the  ‘stty  tostop’  command. 

Status  Reporting 

While  running  interactively,  the  shell  tracks  the  status  of  each  job  and  reports  whenever  a  finishes  or 
becomes  blocked.  It  normally  displays  a  message  to  this  effect  as  it  issues  a  prompt,  so  as  to  avoid  disturb¬ 
ing  the  appearance  of  your  input.  When  set,  the  notify  variable  indicates  that  the  shell  is  to  report  status 
changes  immediately.  By  default,  the  notify  command  marks  the  current  process;  after  starting  a  back¬ 
ground  job,  type  notify  to  mark  it. 

Built-In  Commands 

Built-in  commands  are  executed  within  the  C  shell.  If  a  built-in  command  occurs  as  any  component  of  a 
pipeline  except  the  last,  it  is  executed  in  a  subshell. 

:  Null  command.  This  command  is  interpreted,  but  performs  no  action, 

alias [ name  [def'\] 

Assign  def  to  the  alias  name .  def  is  a  list  of  words  that  may  contain  escaped  history- 
substitution  metasyntax,  name  is  not  allowed  to  be  alias  or  unalias.  If  def  is  omitted,  the  alias 
name  is  displayed  along  with  its  current  definition.  If  both  name  and  d^  are  omitted,  all 
aliases  are  displayed. 

bg  [%job] . . . 

Run  the  current  or  specified  jobs  in  the  background. 

break  Resume  execution  after  the  end  of  the  nearest  enclosing  foreach  or  while  loop.  The  remain¬ 
ing  commands  on  the  current  line  are  executed.  This  allows  multilevel  breaks  to  be  written  as 
a  list  of  break  commands,  all  on  one  line. 

breaksw  Break  from  a  switch,  resuming  after  the  endsw. 

case  label:  A  label  in  a  switch  statement 

Qd[dir] 
chdir  [dfr] 

Change  the  shell’s  working  directory  to  directory  dir.  If  no  argument  is  given,  change  to  the 
home  directory  of  the  user.  If  dir  is  a  relative  pathname  not  found  in  the  current  directory, 
check  for  it  in  those  directories  listed  in  the  cdpath  variable.  If  dir  is  the  name  of  a  shell  vari¬ 
able  whose  value  starts  with  a  /,  change  to  the  directory  named  by  that  value. 

continue  Continue  execution  of  the  nearest  enclosing  while  or  foreach. 

default:  Labels  the  default  case  in  a  switch  statement.  The  default  should  come  after  all  case  labels. 

Any  remaining  commands  on  the  command  line  are  first  executed. 

dirs[~l] 

Print  the  directory  stack,  most  recent  to  the  left;  the  first  directory  shown  is  the  current  direc¬ 
tory.  With  the  -I  argument,  produce  an  unabbreviated  printout;  use  of  the  ~  notation  is 
suppressed. 

echo  [  -n  ]  list 

The  words  in  list  are  written  to  the  shell’s  standard  output,  separated  by  SPACE  characters. 
The  output  is  terminated  with  a  NEWLINE  unless  the  -n  option  is  used. 

eval  argument... 

Reads  the  arguments  as  input  to  the  shell,  and  executes  the  resulting  command(s).  This  is  usu¬ 
ally  used  to  execute  commands  generated  as  the  result  of  command  or  variable  substitution, 
since  parsing  occurs  before  these  substitutions.  See  tset(l)  for  an  example  of  how  to  use  eval. 

exec  command 

Execute  command  in  place  of  the  current  shell,  which  terminates. 
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exit  [  (expr)  ] 

The  shell  exits,  either  with  the  value  of  the  status  variable,  or  with  the  value  of  the  specified 
by  the  expression  expr. 

fg  %  [job] 

Bring  the  current  or  specified  job  into  the  foreground, 
foreach  var  {wordlist) 

end  The  variable  var  is  successively  set  to  each  member  of  wordlist.  The  sequence  of  commands 

between  this  command  and  the  matching  end  is  executed  for  each  new  value  of  var.  (Both 
foreach  and  end  must  appear  alone  on  separate  lines.) 

The  built-in  command  continue  may  be  used  to  continue  the  loop  prematurely  and  the  built-in 
command  break  to  terminate  it  prematurely.  When  this  command  is  read  from  the  terminal, 
the  loop  is  read  up  once  prompting  with  ?  before  any  statements  in  the  loop  are  executed. 

glob  wordlist 

Perform  filename  expansion  on  wordlist.  Like  echo,  but  no  \  escapes  are  recognized.  Words 
are  delimited  by  null  characters  in  the  output. 

goto  label  The  specified  label  is  filename  and  command  expanded  to  yield  a  label.  The  shell  rewinds  its 
input  as  much  as  possible  and  searches  for  a  line  of  the  form  label:  possibly  preceded  by 
SPACE  or  TAB  characters.  Execution  continues  after  the  indicated  line.  It  is  an  error  to  jump 
to  a  label  that  occurs  between  a  while  or  for  built-in,  and  its  corresponding  end. 

hashstat  Print  a  statistics  line  indicating  how  effective  the  internal  hash  table  has  been  at  locating  com¬ 
mands  (and  avoiding  execs).  An  exec  is  attempted  for  each  component  of  the  path  where  the 
hash  function  indicates  a  possible  hit,  and  in  each  component  that  does  not  begin  with  a  7’. 

history  [  -hr  ]  [  n  ] 

Display  the  history  list;  if  n  is  given,  display  only  the  n  most  recent  events. 

-r  Reverse  the  order  of  printout  to  be  most  recent  first  rather  than  oldest  first. 

-h  Display  the  history  list  without  leading  numbers.  This  is  used  to  produce  files  suitable 

for  sourcing  using  the -h  option  to  source. 

if  (expr)  command 

If  the  specified  expression  evaluates  to  true,  the  single  command  with  arguments  is  executed. 
Variable  substitution  on  command  happens  early,  at  the  same  time  it  does  for  the  rest  of  the  if 
command,  command  must  be  a  simple  command,  not  a  pipeline,  a  command  list,  or  a 
parenthesized  command  list.  Note:  I/O  redirection  occurs  even  if  expr  is  false,  when  command 
is  not  executed  (this  is  a  bug), 

if  (expr)  then 
else  if  (expr2)  then 
else 

endif  If  expr  is  true,  commands  up  to  the  first  else  are  executed.  Otherwise,  if  expr2  is  true,  the 
commands  between  the  else  if  and  the  second  else  are  executed.  Otherwise,  commands 
between  the  else  and  the  endif  are  executed.  Any  number  of  else  if  pairs  are  allowed,  but  only 
one  else.  Only  one  endif  is  needed,  but  it  is  required.  The  words  else  and  endif  must  be  the 
first  nonwhite  characters  on  a  line.  The  if  must  appear  alone  on  its  input  line  or  after  an  else.) 

jobs[  -I  ]  List  the  active  jobs  under  job  control. 

-1  List  process  IDs,  in  addition  to  the  normal  information. 
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kill  -1  Send  the  TERM  (terminate)  signal,  by  default,  or  the  signal  specified,  to  the  specified  process 
ID,  the  job  indicated,  or  the  current  Job.  Signals  are  either  given  by  number  or  by  name. 
There  is  no  default.  Typing  kill  does  not  send  a  signal  to  the  current  job.  If  the  signal  being 
sent  is  TERM  (terminate)  or  HUP  (hangup),  then  the  job  or  process  is  sent  a  CONT  (continue) 
signal  as  well. 

-I  List  the  signal  names  that  can  be  sent, 
limit  [  ~h  ]  [  resource  [  max-use  ]  ] 

Limit  the  consumption  by  the  current  process  or  any  process  it  spawns,  each  not  to  exceed 
max-use  on  the  specified  resource.  If  max-use  is  omitted,  print  the  current  limit;  if  resource  is 
omitted,  display  all  limits. 

-h  Use  hard  limits  instead  of  the  current  limits.  Hard  limits  impose  a  ceiling  on  the 
values  of  the  current  limits.  Only  the  super-user  may  raise  the  hard  limits. 

resource  is  one  of: 

cputime  Maximum  CPU  seconds  per  process, 

filesize  Largest  single  file  allowed. 

datasize  Maximum  data  size  (including  stack)  for  the  process, 

stacksize  Maximum  stack  size  for  the  process, 

coredumpsize  Maximum  size  of  a  core  dump  (file), 
descriptors  Maximum  value  for  a  file  descriptor, 

max-use  is  a  number,  with  an  optional  scaling  factor,  as  follows: 

nh  Hours  (for  cputime). 

nk  n  kilobytes.  This  is  the  default  for  all  but  cputime. 

nm  n  megabytes  or  minutes  (for  cputime). 

mm  155  Minutes  and  seconds  (for  cputime). 

login  [  username  l-p  ] 

Terminate  a  login  shell  and  invoke  login(l).  The  .logout  file  is  not  processed.  If  username  is 
omitted,  login  prompts  for  the  name  of  a  user. 

”P  Preserve  the  current  environment  (variables). 

logout  Terminate  a  login  shell. 

nice  [  +n  l-n  ]  [  command  ] 

Increment  the  process  priority  value  for  the  shell  or  for  command  by  n.  The  higher  the  priority 
value,  the  lower  the  priority  of  a  process,  and  the  slower  it  runs.  When  given,  command  is 
always  run  in  a  subshell,  and  the  restrictions  placed  on  commands  in  simple  if  commands 
apply.  If  command  is  omitted,  nice  increments  the  value  for  the  current  shell.  If  no  increment 
is  specified,  nice  sets  the  nice  value  to  4.  The  range  of  nice  values  is  from  -20  through  19. 
Values  of  n  outside  this  range  set  the  value  to  the  lower,  or  to  the  higher  boundary,  respec¬ 
tively. 

+n  Increment  the  process  priority  value  by  n . 

~n  Decrement  by  n.  This  argument  can  be  used  only  by  the  super-user, 

nohup  [  command  ] 

Run  command  with  HUPs  ignored.  With  no  arguments,  ignore  HUPs  throughout  the  remainder 
of  a  script.  When  given,  command  is  always  run  in  a  siibshell,  and  the  restrictions  placed  on 
commands  in  simple  if  commands  apply.  All  processes  detached  with  &  are  effectively 
nohup'd. 

notify  [  %jobl ... 

Notify  the  user  asynchronously  when  the  status  of  the  current,  or  of  specified  jobs,  changes. 
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onintr  [  - 1  label] 

Control  the  action  of  the  shell  on  interrupts.  With  no  arguments,  onintr  restores  the  default 
action  of  the  shell  on  interrupts.  (The  sheU  terminates  shell  scripts  and  returns  to  the  terminal 
command  input  level).  With  the  -  argument,  the  shell  ignores  all  interrupts.  With  a  label 
argument,  the  shell  executes  a  goto  label  when  an  interrupt  is  received  or  a  child  process  ter¬ 
minates  because  it  was  intemipted. 

popd  [+n] 

Pop  die  directory  stack,  and  cds  to  the  new  top  directory.  The  elements  of  the  directory  stack 
are  numbered  from  0  starting  at  the  top. 

+n  Discard  the  n  ’th  entry  in  the  stack. 

pushd  [+n  I  dir] 

Push  a  directory  onto  the  directory  stack.  With  no  arguments,  exchange  the  top  two  elements. 

+n  Rotate  the  n  ’th  entry  to  the  top  of  the  stack  and  cd  to  it. 

dir  Push  the  current  working  directory  onto  the  stack  and  change  to  dir. 

rehash  Recompute  the  internal  hash  table  of  the  contents  of  directories  listed  in  the  path  variable  to 
account  for  new  commands  added. 

repeat  count  command 

Repeat  command  count  times  command  is  subject  to  the  same  restrictions  as  with  the  one-line 
if  statement. 

set  [var  [  =  value  ]  ] 
set  var[n]  =  word 

With  no  arguments,  set  displays  the  values  of  all  shell  variables.  Multiword  values  are 
displayed  as  a  parenthesized  list.  With  the  var  argument  alone,  set  assigns  an  empty  (null) 
value  to  the  variable  var.  With  arguments  of  the  form  var  =  value  set  assigns  value  to  var, 
where  value  is  one  of: 

word  A  single  word  (or  quoted  string). 

(wordlist)  A  space-separated  list  of  words  enclosed  in  parentheses. 

Values  are  command  and  filename  expanded  before  being  assigned.  The  form  set  var[n]  = 
word  replaces  the  /I’th  word  in  a  multiword  value  with  word. 

setenv  [  VAR  [  word  ]  ] 

With  no  arguments,  setenv  displays  all  environment  variables.  With  the  VAR  argument  sets  the 
environment  variable  VAR  to  have  an  empty  (null)  value.  (By  convention,  environment  vari¬ 
ables  are  normally  given  upper-case  names.)  With  both  VAR  and  word  arguments  setenv  sets 
the  environment  variable  NAME  to  the  value  word,  which  must  be  either  a  single  word  or  a 
quoted  string.  The  most  commonly  used  environment  variables,  USER,  TERM,  and  PATH,  are 
automatically  imported  to  and  exported  from  the  csh  variables  user,  term,  and  path;  there  is 
no  need  to  use  setenv  for  these.  In  addition,  the  shell  sets  the  PWD  environment  variable  from 
the  csh  variable  cwd  whenever  the  latter  changes. 

shift  [  variable  ] 

The  components  of  argv,  or  variable,  if  supplied,  are  shifted  to  the  left,  discarding  the  first 
component.  It  is  an  error  for  the  variable  not  to  be  set,  or  to  have  a  null  value. 

source  [  -h  ]  name 

Reads  commands  from  name,  source  commands  may  be  nested,  but  if  they  are  nested  too 
deeply  the  shell  may  run  out  of  file  descriptors.  An  error  in  a  sourced  file  at  any  level  ter- 
“  minates  all  nested  source  commands. 

-h  Place  commands  from  the  file  name  on  the  history  list  without  executing  them. 
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stop  [%job] . . . 

Stop  the  current  or  specified  background  job. 

suspend  Stop  the  shell  in  its  tracks,  much  as  if  it  had  been  sent  a  stop  signal  with  *Z.  This  is  most  often 
used  to  stop  shells  started  by  su. 

switch  (string) 
case  label: 

breaksw 

default: 

breaksw 

endsw  Each  label  is  successively  matched,  against  the  specified  string,  which  is  first  command  and 
filename  expanded.  The  file  metacharacters  *,  ?  and  [. ..]  may  be  used  in  the  case  labels, 
which  are  variable  expanded.  If  none  of  the  labels  match  before  a  “default”  label  is  found, 
execution  begins  after  the  default  label.  Each  case  statement  and  the  default  statement  must 
appear  at  the  beginning  of  a  line.  The  command  breaksw  continues  execution  after  the 
endsw.  Otherwise  control  falls  through  subsequent  case  and  default  statements  as  with  C.  If 
no  label  matches  and  there  is  no  default,  execution  continues  after  the  endsw. 

time  [  command  ] 

With  no  argument,  print  a  summary  of  time  used  by  this  C  shell  and  its  children.  With  an 
optional  command,  execute  command  and  print  a  summary  of  the  time  it  uses. 

umask  [  value  ] 

Display  the  file  creation  mask.  With  value  set  the  file  creation  mask,  value  is  given  in  octal, 
and  is  XORed  with  the  permissions  of  666  for  files  and  111  for  directories  to  arrive  at  the  per¬ 
missions  for  new  files.  Common  values  include  002,  giving  complete  access  to  the  group,  and 
read  (and  directory  search)  access  to  others,  or  022,  giving  read  (and  directory  search)  but  not 
write  permission  to  the  group  and  others. 

pattern 

Discard  aliases  that  match  (filename  substitution)  pattern.  All  aliases  are  removed  by 
unalias  *. 

unhash  Disable  the  internal  hash  table, 
unlimit  [  -h  ]  [  resource  ] 

Remove  a  limitation  on  resource .  If  no  resource  is  specified,  then  all  resource  limitations  are 
removed.  See  the  description  of  the  limit  command  for  the  list  of  resource  names. 

-h  Remove  corresponding  hard  limits.  Only  the  super-user  may  do  this, 
unset  pattern 

Remove  variables  whose  names  match  (filename  substitution)  pattern.  All  variables  are 
removed  by  ‘unset  this  has  noticeably  distasteful  side-effects. 

unsetenv  variable 

Remove  variable  from  the  environment.  Pattern  matching,  as  with  unset  is  not  performed, 
wait  Wait  for  background  jobs  to  finish  (or  for  an  interrupt)  before  prompting, 
while  (e^r) 

end  While  expr  is  true  (evaluates  to  non-zero),  repeat  commands  between  the  while  and  the  match¬ 

ing  end  statement,  break  and  continue  may  be  used  to  terminate  or  continue  the  loop  prema¬ 
turely.  The  while  and  end  must  app)ear  alone  on  their  input  lines.  If  the  shell’s  input  is  a  ter¬ 
minal,  it  prompts  for  commands  with  a  question-mark  until  the  end  command  is  entered  and 
then  performs  the  commands  in  the  loop. 


no 


Last  change:  2  October  1989 


Sun  Release  4.1 


CSH(l) 


USER  COMMANDS 


CSH(l) 


%[job][8i] 

Bring  the  current  or  indicated  job  to  the  foreground.  With  the  ampersand,  continue  running 
job  in  the  background. 

@  [  var  =expr  ] 

@  [  var[n]  =expr  ] 

With  no  arguments,  display  the  values  for  all  shell  variables.  With  arguments,  the  variable 
var,  or  the  /I  ’th  word  in  the  value  of  var,  to  the  value  that  expr  evaluates  to.  (If  [n]  is  supplied, 
both  var  and  its  /I’th  component  must  already  exist.) 

If  the  expression  contains  the  characters  >,  <,  &  or  |,  then  at  least  this  part  of  expr  must  be 
placed  within  parentheses. 

The  operators  *=,  +=,  etc.,  are  available  as  in  C.  The  space  separating  the  name  from  the 
assignment  operator  is  optional.  Spaces  are,  however,  mandatory  in  separating  components  of 
expr  that  would  otherwise  be  single  words. 

Special  postfix  operators,  +  +  and  —  increment  or  decrement  name,  respectively. 

Environment  Variables  and  Predefined  Shell  Variables 


Unlike  the  standard  shell,  the  C  shell  maintains  a  distinction  between  environment  variables,  which  are 
automaticaUy  exported  to  processes  it  invokes,  and  shell  variables,  which  are  not.  Both  types  of  variables 
are  treated  similarly  under  variable  substitution.  The  shell  sets  the  variables  argv,  cwd,  home,  path, 
prompt,  shell,  and  status  upon  initialization.  The  shell  copies  the  environment  variable  USER  into  die 
shell  variable  user,  TERM  into  term,  and  HOME  into  home,  and  copies  each  back  into  the  respecdve 
environment  variable  whenever  the  shell  variables  are  reset.  PATH  and  path  are  similarly  handled.  You 
need  only  set  path  once  in  the  .cshrc  or  .login  file.  The  environment  variable  PWD  is  set  from  cwd  when¬ 
ever  the  latter  changes.  The  following  shell  variables  have  predefined  meanings: 

argv 

Argument  list.  Contains  the  list  of  command  line  arguments  supplied  to  the  current 
invocation  of  the  shell.  This  variable  determines  the  value  of  the  positional  parame¬ 
ters  $1,  $2,  and  so  on. 

cdpath 

Contains  a  list  of  directories  to  be  searched  by  the  cd,  chdir,  and  popd  commands,  if 
the  directory  argument  each  accepts  is  not  a  subdirectory  of  the  current  directory. 

cwd 

The  full  pathname  of  the  current  directory. 

echo 

Echo  commands  (after  substitutions),  just  before  execution. 

fignore 

A  list  of  filename  suffixes  to  ignore  when  attempting  filename  completion.  Typically 
the  single  word  ‘.o’. 

filec 

Enable  filename  completion,  in  which  case  the  CTRL-D  character  CTRL-D)  and  the 
ESC  character  have  special  significance  when  typed  in  at  the  end  of  a  terminal  input 
line: 

EOT  Print  a  list  of  all  filenames  that  start  with  the  preceding  string. 

ESC  Replace  the  preceding  string  with  the  longest  unambiguous  extension. 

hardpaths 

If  set,  pathnames  in  the  directory  stack  are  resolved  to  contain  no  symbolic-link 
components. 

histchars 

A  two-character  string.  The  first  character  replaces  1  as  the  history-substitution  char¬ 
acter.  The  second  replaces  the  carat  (^)  for  quick  substitutions. 

history 

The  number  of  lines  saved  in  the  history  list.  A  very  large  number  may  use  up  all  of 
the  C  shell’s  memory.  If  not  set,  the  C  shell  saves  only  the  most  recent  command. 

home 

The  user’s  home  directory.  The  filename  expansion  of  refers  to  the  value  of  this 
variable. 

ignoreeof 

If  set,  the  shell  ignores  EOF  from  terminals.  This  protects  against  accidentally  killing 
a  C  shell  by  typing  a  CTRL-D. 
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mail 

nobeep 

noclobber 

noglob 

nonomatch 

notify 

path 


prompt 


savehist 

shell 

status 

time 


A  list  of  files  where  the  C  shell  checks  for  mail.  If  the  first  word  of  the  value  is  a 
number,  it  specifies  a  mail  checking  interval  in  seconds  (default  5  minutes). 

Suppress  the  bell  during  command  completion  when  asking  the  C  shell  to  extend  an 
ambiguous  filename. 

Restrict  output  redirection  so  that  existing  files  are  not  destroyed  by  accident.  > 
redirections  can  only  be  made  to  new  files.  »  redirections  can  only  be  made  to 
existing  files. 

Inhibit  filename  substitution.  This  is  most  useful  in  shell  scripts  once  filenames  (if 
any)  are  obtained  and  no  further  expansion  is  desired. 

Returns  the  filename  substitution  pattern,  rather  than  an  error,  if  the  pattern  is  not 
matched.  Malformed  patterns  still  result  in  errors. 

If  set,  the  shell  notifies  you  immediately  as  jobs  are  completed,  rather  than  waiting 
until  just  before  issuing  a  prompt 

The  list  of  directories  in  which  to  search  for  commands,  path  is  initialized  from  the 
environment  variable  PATH,  which  the  C  shell  updates  whenever  path  changes.  A 
null  word  specifies  the  current  directory.  The  default  is  typically:  (.  /usr/ucb 
/usr/bin).  If  path  becomes  unset  only  full  pathnames  will  execute.  An  interactive  C 
shell  will  normally  hash  the  contents  of  the  directories  listed  after  reading  .cshrc, 
and  whenever  path  is  reset.  If  new  commands  are  added,  use  the  rehash  command 
to  update  the  table. 

The  string  an  interactive  C  shell  prompts  with.  Noninteractive  shells  leave  the 
prompt  variable  unset.  Aliases  and  other  commands  in  the  .cshrc  file  that  are  only 
useful  interactively,  can  be  placed  after  the  following  test  ‘if  ($? prompt  ==  0) 
exit’,  to  reduce  startup  time  for  noninteractive  shells.  A  !  in  the  prompt  string  is 
replaced  by  the  current  event  number.  The  default  prompt  is  hostname  %  for  mere 
mortals,  or  hostnameit  for  the  super-user. 

The  number  of  lines  from  the  history  list  that  are  saved  in  “/.history  when  the  user 
logs  out.  Large  values  for  savehist  slow  down  the  C  shell  during  startup. 

The  file  in  which  the  C  shell  resides.  This  is  used  in  forking  shells  to  interpret  files 
that  have  execute  bits  set,  but  that  are  not  executable  by  the  system. 

The  status  returned  by  the  most  recent  command.  If  that  command  terminated 
abnormally,  0200  is  added  to  the  status.  Built-in  commands  that  fail  return  exit 
status  1,  all  other  built-in  commands  set  status  to  0. 

Control  automatic  timing  of  commands.  Can  be  supplied  with  one  or  two  values. 
The  first  is  the  reporting  threshold  in  CPU  seconds.  The  second  is  a  string  of  tags  and 
text  indicating  which  resources  to  report  on.  A  tag  is  a  percent  sign  (%)  followed 
by  a  single  upper-case  letter  (unrecognized  tags  print  as  text): 

%D  Average  amount  of  unshared  data  space  used  in  Kilobytes. 

%E  Elapsed  (wallclock)  time  for  the  command. 

%F  Page  faults. 

%1  Number  of  block  input  operations. 

%K  Average  amount  of  unshared  stack  space  used  in  Kilobytes. 

%M  Maximum  real  memory  used  during  execution  of  the  process. 

%  O  Number  of  block  output  operations. 

%P  Total  CPU  time  —  U  (user)  plus  S  (system)  —  as  a  percentage  of  E 
(elapsed)  time. 
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%S  Number  of  seconds  of  CPU  time  consumed  by  the  kernel  on  behalf 
of  the  user’s  process. 

%U  Number  of  seconds  of  CPU  time  devoted  to  the  user’s  process. 

%  W  Number  of  swaps. 

%X  Average  amount  of  shared  memory  used  in  Kilobytes. 

The  default  summary  display  outputs  from  the  %U,  %S,  %E,  %P,  %X,  %D,  %I, 
%0,  %¥  and  %W  tags,  in  that  order. 

verbose  Display  each  command  after  history  substitution  takes  place. 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  all  command  line  parsing.  These  variables  are  checked  in  the  following  order  LC  CTYPE, 
LANG,  and  LC_default  When  a  valid  value  is  found,  remaining  environment  variables  for  character 
classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current  valid  charac¬ 
ter  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character  classification 
defaults  to  the  POSDC.l  “C"  locale. 

FILES 

~/.cshrc 
“/.login 
/.logout 
“/.history 
/impish* 

/etc/passwd 

SEE  ALSO 

login(l),  printenv(l),  sh(l),  tset(l),  access(2V),  execve(2V),  fork(2V),  pipe(2V),  termio(4),  a.out(5), 
environ(5V),  locale(5),  ascu(7),  iso_8859 J(7) 

SunOS  User's  Guide:  Doing  More 
SunOS  User's  Guide:  Getting  Started 

DIAGNOSTICS 

You  have  stopped  jobs. 

You  attempted  to  exit  the  C  shell  with  stopped  jobs  under  job  control.  An  immediate  second 
attempt  to  exit  will  succeed,  terminating  the  stopped  jobs. 

LIMITATIONS 

Words  can  be  no  longer  than  1024  characters.  The  system  limits  argument  lists  to  1,048,576  characters. 
However,  the  maximum  number  of  arguments  to  a  command  for  which  filename  expansion  applies  is  1706. 
Command  substitutions  may  expand  to  no  more  characters  than  are  allowed  in  the  argument  list.  To  detect 
looping,  the  shell  restricts  the  number  of  alias  substitutions  on  a  single  line  to  20. 

BUGS 

When  a  command  is  restarted  from  a  stop,  the  shell  prints  the  directory  it  started  in  if  this  is  different  from 
the  current  directory;  this  can  be  misleading  (that  is,  wrong)  as  the  job  may  have  changed  directories  inter¬ 
nally. 

Shell  built-in  functions  are  not  stoppable/restartable.  Command  sequences  of  the  form  a  ;  /?  ;  c  are  also  not 
handled  gracefully  when  stopping  is  attempted.  If  you  suspend  6,  the  shell  never  executes  c.  This  is  espe¬ 
cially  noticeable  if  the  expansion  results  from  an  alias.  It  can  be  avoided  by  placing  the  sequence  in 
parentheses  to  force  it  into  a  subshell. 

Control  over  terminal  output  after  processes  are  started  is  primitive;  use  the  Sun  Window  system  if  you 
need  better  output  control. 

Multiline  shell  procedures  should  be  provided,  as  they  arc  with  the  standard  (Bourne)  shell. 


Read  at  beginning  of  execution  by  each  shell. 
Read  by  login  shells  after  .cshrc  at  login. 
Read  by  login  shells  at  logout. 

Saved  history  for  use  at  next  login. 
Temporary  file  for 

Source  of  home  directories  for  '^name' . 
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Commands  within  loops,  prompted  for  by  ?,  are  not  placed  in  the  history  list. 

Control  structures  should  be  parsed  rather  than  being  recognized  as  built-in  commands.  This  would  allow 
control  commands  to  be  placed  anywhere,  to  be  combined  with  |,  and  to  be  used  with  &  and ;  metasyntax. 

It  should  be  possible  to  use  the  :  modifiers  on  the  output  of  command  substitutions.  There  are  two  prob¬ 
lems  with  ;  modifier  usage  on  variable  substitutions:  not  all  of  the  modifiers  are  available,  and  only  one 
modifier  per  substitution  is  allowed. 

The  g  (global)  flag  in  history  substitutions  applies  only  to  the  first  match  in  each  word,  rather  than  all 
matches  in  all  words.  The  standard  text  editors  consistently  do  the  latter  when  given  the  g  flag  in  a  substitu¬ 
tion  command. 

Quoting  conventions  are  confusing.  Overriding  the  escape  character  to  force  variable  substitutions  within 
double  quotes  is  counterintuitive  and  inconsistent  with  the  Bourne  shell. 

Symbolic  links  can  fool  the  shell.  Setting  the  hardpaths  variable  alleviates  this. 

‘set  path’  should  remove  duplicate  pathnames  from  the  pathname  list.  These  often  occur  because  a  shell 
script  or  a  .cshrc  file  does  something  like  ‘set  path=(/usr/local  /usr/hosts  $path)’  to  ensure  that  the 
named  directories  are  in  the  pathname  list. 

The  only  way  to  direct  the  standard  output  and  standard  enor  separately  is  by  invoking  a  subshell,  as  fol¬ 
lows: 

example%  (command >  outfile)  >&  errorfile 

Although  robust  enough  for  general  use,  adventures  into  the  esoteric  periphery  of  the  C  shell  may  reveal 
unexpected  quirks. 
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NAME 

csplit  -  split  a  file  with  respect  to  a  given  context 
SYNOPSIS 

csplit  [  prefix  ]  [  -k  ]  [  -s  ]  filename  argument!  [ . .  .argumentn  ] 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

csplit  reads  the  file  whose  name  is  filename  and  separates  it  into  n+l  sections,  defined  by  the  arguments 
argument!  through  argumentn.  If  filename  argument  is  a  the  standard  input  is  used.  By  default  the 
sections  are  placed  in  files  named  xxOO  through  xxn.  n  may  not  be  greater  than  99,  These  sections  receive 
the  following  portions  of  the  file: 

xxOO  From  the  start  of  filename  up  to  (but  not  including)  the  line  indicated  by  argument!  (see 

OPTIONS  below  for  an  explanation  of  these  arguments.) 
xxOl:  From  the  line  indicated  by  argument!  up  to  the  line  indicated  by  argum€nt2 . 

xxw:  From  the  line  referenced  by  argumentn  to  the  end  of  filename , 

csplit  prints  the  character  counts  for  each  file  created,  and  removes  any  files  it  creates  if  an  error  occurs. 
OPTIONS 

-f  prefix  name  the  created  files  prefix^l!  through  prefixn . 

-k  Suppress  removal  of  created  files  when  an  error  occurs. 

-s  Suppress  printing  of  character  counts. 

The  arguments  argument!  through  argumentn  can  be  a  combination  of  the  following  selection  operators: 

Irexpl  A  file  is  to  be  created  for  the  section  from  the  current  line  up  to  (but  not  including)  the  line 

containing  the  regular  expression  rexp.  The  current  line  then  becomes  the  line  containing 
rexp.  This  argument  may  be  followed  by  an  optional  *+’  or  some  number  of  lines  (for 
example,  /Page/-5). 

%rexp  %  This  argument  is  the  same  as  Irexpl,  except  that  no  file  is  created  for  the  selected  section. 

lineno  A  file  is  to  be  created  from  the  current  line  up  to  (but  not  including)  lineno.  The  current  line 

becomes  lineno. 

{num )  Repeat  argument.  This  argument  may  follow  any  of  the  above  arguments.  If  it  follows  a 

rexp  type  argument,  that  argument  is  applied  num  more  times.  If  it  follows  lineno ,  the  file 
will  be  split  every  lineno  lines  {num  times)  from  that  point. 

Enclose  all  rexp  type  arguments  that  contain  blanks  or  other  characters  meaningful  to  the  shell  in  the 
appropriate  quotes.  Regular  expressions  may  not  contain  embedded  new-lines. 

EXAMPLES 

This  example  splits  the  file  at  every  100  lines,  up  to  10,000  lines, 
csplit -k  file  100  {99} 

Assuming  that  prog.c  follows  the  normal  C  coding  convention  of  ending  routines  with  a  }  at  the  beginning 
of  the  line,  this  example  will  create  a  file  containing  each  separate  C  routine  (up  to  21)  in  prog.c. 

csplit -k prog.c  '%main(%'  7"}/+!'  {20} 

SEE  ALSO 

ed(l),sh(l),regexp(3) 
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DIAGNOSTICS 

Self-explanatory  except  for 

arg  -  out  of  range 

which  means  that  the  given  argument  did  not  refer  to  a  line  between  the  current  position  and  the  EOF. 
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NAME 

ctags  -  create  a  tags  file  for  use  with  ex  and  vi 

SYNOPSIS 

Ctags  [  -aBFtuvwx  ]  [  ~f  tagsfde  ]  filename ... 

DESCRIPTION 

ctags  makes  a  tags  file  for  ex(l)  from  the  specified  C,  Pascal,  FORTRAN,  yacc(l),  and  lex(l)  sources,  A 
tags  file  gives  the  locations  of  specified  objects  (in  this  case  functions  and  type  definitions)  in  a  group  of 
files.  Each  entry  in  the  tags  is  composed  of  three  fields  separated  by  white  space,  the  object  name,  the  file 
in  which  it  is  defined,  and  an  address  specification.  Function  definitions  are  located  using  regular  expres¬ 
sion  patterns,  type  definitions,  using  a  line  number. 

ex  and  vi(l)  use  entries  in  the  tags  file  to  locate  and  display  a  definition. 

Normally  ctags  places  the  tag  descriptions  in  a  file  called  tags;  this  may  be  overridden  with  the  -f  option. 
By  default,  the  tags  file  is  sorted  in  lexicographic  (ASCII)  order,  and  ex  expects  its  entries  to  be  so  sorted. 

Files  with  names  ending  in  .c  or  .h  are  assumed  to  be  C  source  files  and  are  searched  for  C  routine  and 
macro  definitions.  Files  with  names  ending  in  .y  are  assumed  to  be  yacc  source  files.  Files  with  names 
ending  in  .1  are  assumed  to  be  lex  files.  Others  are  first  examined  to  see  if  they  contain  any  Pascal  or  FOR¬ 
TRAN  routine  definitions;  if  not,  they  are  processed  again  looking  for  C  definitions. 

The  tag  for  the  main( )  function  is  treated  specially  in  C  programs.  The  tag  formed  is  created  by  prepend¬ 
ing  M  to  filename ,  with  a  trailing  .c  removed,  if  any,  and  leading  pathname  components  also  removed.  This 
makes  use  of  ctags  practical  in  directories  with  more  than  one  program. 

OPTIONS 

-a  Append  output  to  an  existing  tags  file.  The  resulting  file  is  not  sorted.  To  preserve  the  order,  use 
-u  instead. 

-B  Use  backward  searching  patterns  (?. . .  ?). 

-F  Use  forward  searching  patterns  (/. . .  /)  (default). 

Create  tags  for  typedefs. 

-u  Update  the  specified  files  in  the  tags  file.  Entries  that  refer  to  them  are  deleted  and  then  replaced 
in  lexicographic  order.  Beware:  this  option  is  implemented  in  a  way  which  is  rather  slow;  it  may 
be  faster  simply  to  rebuild  the  tags  file. 

-v  Produce  an  index  of  the  form  expected  by  vgrind(l)  on  the  standard  output.  This  listing  contains 
the  function  name,  file  name,  and  page  number  (assuming  64  line  pages).  Since  the  output  will  be 
sorted  into  lexicographic  order,  it  may  be  desired  to  run  the  output  through  ‘sort  -f’.  See  EXAM¬ 
PLES. 

-w  Suppress  warning  diagnostics. 

-X  Produce  a  list  of  object  names,  the  line  number  and  file  name  on  which  each  is  defined,  as  well  as 
the  text  of  that  line  and  prints  this  on  the  standard  output.  This  is  a  simple  index  which  can  be 
printed  out  as  an  off-line  readable  function  index. 

EXAMPLES 

Using  ctags  with  the  -v  option  produces  entries  in  an  order  which  may  not  always  be  appropriate  for 
vgrind.  To  produce  results  in  alphabetical  order,  you  may  want  to  run  the  output  through  ‘sort  -f’. 

example  %  ctags  -v  filename.c  filename.h  1  sort  -f  >  index 
example%  vgrind  -x  index 
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To  build  a  tags  file  for  C  sources  in  a  directory  hierarchy,  first  create  an  empty  tags  file,  and  then  run  the 
following  find(l)  command: 

example  %  cd  7src  ;  rm  -f  tags  ;  touch  tags 

example%  find  7src  \(  -name  ’*.c’  -o  -name  \)  -exec  ctags  -u  -f  /usr/src/tags  {}  \; 

FILES 

tags  output  tags  file 

SEE  ALSO 

cc(lV),  ex(l),  find(l),  vgrind(l),  vi(l) 

NOTES 

While  the  compiler  allows  8-bit  strings  and  comments,  8-bits  are  not  allowed  anywhere  else.  See  cc(lV) 
for  an  explanation  about  why  cc  is  not  8-bit  clean. 

BUGS 

Recognition  of  functions,  subroutines  and  procedures  for  FORTRAN  and  Pascal  is  done  is  a  very  sim- 
pleminded  way.  No  attempt  is  made  to  deal  with  block  structure;  if  you  have  two  Pascal  procedures  in  dif¬ 
ferent  blocks  with  the  same  name,  ctags  will  only  make  an  entry  for  one. 

ctags  does  not  know  about  #ifdefs. 

ctags  should  know  about  Pascal  types.  Relies  on  the  input  being  well  formed  to  detect  typedefs.  Use  of 
-tx  shows  only  the  last  line  of  typedefs. 
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NAME 

ctrace  -  generate  a  C  program  execution  trace 
SYNOPSIS 

ctrace  [~r functions]  [-y functions]  [-o  x u e ]  [-s Pb ]  [-1 « ]  [-t « ]  [ ]  [-b  ]  [-p  ’  j  ’  ] 

[  -r /]  [filename  ] 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4J 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

ctrace  allows  you  to  follow  the  execution  of  a  C  program,  statement  by  statement.  The  effect  is  similar  to 
executing  a  shell  procedure  with  the  -x  option,  ctrace  reads  the  C  program  in  filename  (or  from  standard 
input  if  you  do  not  s^iiy  filename),  inserts  statements  to  print  the  text  of  each  executable  statement  and 
the  values  of  all  variables  referenced  or  modified,  and  writes  the  modified  program  to  the  standard  output. 
You  must  put  the  output  of  ctrace  into  a  temporary  file  because  the  cc(lV)  command  does  not  allow  the 
use  of  a  pipe.  You  then  compile  and  execute  this  file. 

As  each  statement  in  the  program  executes  it  will  be  listed  at  the  terminal,  followed  by  the  name  and  value 
of  any  variables  referenced  or  modified  in  the  statement,  followed  by  any  output  from  the  statement. 
Loops  in  the  trace  output  are  detected  and  tracing  is  stopped  until  the  loop  is  exited  or  a  different  sequence 
of  statements  within  the  loop  is  executed. 

A  warning  message  is  printed  every  1000  times  through  the  loop  to  help  you  detect  infinite  loops.  The 
trace  output  goes  to  the  standard  output  so  you  can  put  it  into  a  file  for  examination  with  an  editor  or  the 
tail(l)  command. 

OPTIONS 

-f  functions  Trace  only  these  functions, 

functions  Trace  all  but  thtsQ  functions. 

You  may  want  to  add  to  the  default  formats  for  printing  variables,  long  and  pointer  variables  are  always 
printed  as  signed  integers.  Pointers  to  character  arrays  are  printed  as  strings  if  appropriate,  char,  short, 
and  int  variables  are  printed  as  signed  integers  and,  if  apfffopriate,  as  characters,  double  variables  are 
printed  as  floating-point  numbers  in  scientific  notation.  You  can  request  that  variables  be  printed  in  addi¬ 
tional  formats,  if  appropriate,  with  these  options: 

-o  Octal. 

-X  Hexadecimal. 

~u  Unsigned. 

~e  Floating  point. 

These  options  are  used  only  in  special  circumstances: 

-1  n  Check  n  consecutively  executed  statements  for  looping  trace  output,  instead  of  the  default 

of  20.  Use  0  to  get  all  the  trace  output  from  loops. 

-s  Suppress  redundant  trace  output  from  simple  assignment  statements  and  string  copy  func¬ 

tion  calls.  This  option  can  hide  a  bug  caused  by  use  of  the  =  operator  in  place  of  the  =  = 
operator. 

~t  n  Trace  n  variables  per  statement  instead  of  the  default  of  10  (the  maximum  number  is  20). 

The  DIAGNOSTICS  section  explains  when  to  use  this  option. 

-P  Run  the  C  preprocessor  on  the  input  before  tracing  it.  You  can  also  use  the  ~D,  -I,  and  ~U 

cc(lV)  options. 
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These  options  are  used  to  tailor  the  run-time  trace  package  when  the  traced  program  will  run  in  a  non-UNIX 
system  environment: 


~b  Use  only  basic  functions  in  the  trace  code,  that  is,  those  in  ctype(3V),  printf(3V),  and 

string(3).  These  are  often  available  even  in  cross-compilers  for  microprocessors.  In  partic¬ 
ular,  this  option  is  needed  when  the  traced  program  runs  under  an  operating  system  that 
does  not  have  signal(3V),  fflush,  longjmp  or  setjmp(3V)  (see  fclose(3V)  and  setjmp(3V)). 
-p  ’s’  Change  the  trace  print  function  from  the  default  of  ’printf(’.  For  example,  ’fprintf(stderr’ 

would  send  the  trace  to  the  standard  error  output. 

-r/  Use  file/in  place  of  the  runtime,  c  trace  function  package.  This  lets  you  change  the  entire 

print  function,  instead  of  just  the  name  and  leading  arguments  (see  the  -p  option). 


USAGE 

Execution-Time  Trace  Control 

The  default  operation  for  ctrace  is  to  trace  the  entire  program  file,  unless  you  use  the  -f  or  -v  options  to 
trace  specific  functions.  This  does  not  give  you  statement  by  statement  control  of  the  tracing,  nor  does  it  let 
you  turn  the  tracing  off  and  on  when  executing  the  tracedprogram. 


You  can  do  both  of  these  by  adding  ctroff( )  and  ctron()  function  calls  to  your  program  to  turn  the  fracing 
off  and  on,  respectively,  at  execution  time.  Thus,  you  can  code  arbitrarily  complex  criteria  for  trace  con¬ 
trol  with  if  statements,  and  you  can  even  conditionally  include  this  code  because  ctrace  defines  the 
CTRACE  preprocessor  variable.  For  example: 

#ifdef 

CTRACE 

if(c  >  1000) 

ctron(); 

#endif 

You  can  also  call  these  functions  from  dbx(l)  if  you  compile  with  the  -g  option.  For  example,  to  trace  all 
but  lines  7  to  10  in  the  primary  source  file,  enter: 
dbx  a.  out 

when  at  7  {  call  ctroff( );  cont;  } 
when  at  11  {  call  ctron( );  cont; } 
run 

You  can  also  turn  the  trace  off  and  on  by  setting  the  static  variable  tr_ct_  to  0  and  1,  respectively.  This  is 
useful  if  you  are  using  a  debugger  that  cannot  call  these  functions  directly,  such  as  adb(l). 


EXAMPLES 

If  the  file  Ic.  c  contains  this  C  program: 

#include  <stdio.  h> 

main()  /*  count  lines  in  input  */ 

{ 

int  Cf  nl; 
nl  =  0; 

while  ((c  =  getcharO)  !=  EOF) 
if(c  =  ’\n’) 

-n-nl; 

printfr%d\n'',nl); 

} 

and  you  enter  these  commands  and  lest  data: 
cc  Ic.  c 
a.  out 
1 

CTRL-D, 

the  program  will  be  compiled  and  executed.  The  output  of  the  program  will  be  the  number  2,  which  is  not 
correct  because  there  is  only  one  line  in  the  test  data.  The  error  in  this  program  is  common,  but  subtle. 
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If  you  invoke  ctrace  with  these  commands: 
ctrace  Ic.  c  >temp.c 
cc  temp,  c 
a.  out 

the  output  will  be: 
main( ) 

nl  =  0; 

/*  nl  ==  0  */ 

while  ((c  =  getchar( ))  !=  EOF) 

The  program  is  now  waiting  for  input.  If  you  enter  the  same  test  data  as  before,  the  output  will  be: 

/♦  c  ==  49  or  *1’  */ 
if  (c  =  *\n’) 

/*  c  ==  10  or  ’\n’  */ 

++nl; 

/♦  nl  ==  1  +/ 
while  ((c  =  getchar( ))  !=  EOF) 

/♦  c  ==  10  or  ’\n’  */ 
if  (c  =  ’\n’) 

/+  c  ==  10  or  ’\n’  +/ 

++nl; 

/♦  nl  ==  2  */ 

/*  repeating  */ 

If  you  now  enter  an  end  of  file  character  (CTRL-D)  the  final  output  will  be: 

/*  repeated  <1  time  +/ 

while  ((c  =  getcharO)  !=  EOF) 

/*  c  ==  -1  */ 
printf("%d\n",nl)5 
/♦  nl  ==  2  *12 
f*  return  */ 

Program  output  is  printed  at  the  end  of  the  trace  line  for  the  nl  variable.  Also  note  the  return  comment 
added  by  ctrace  at  the  end  of  the  trace  output.  This  shows  the  implicit  return  at  the  terminating  brace  in 
the  function. 

The  trace  output  shows  that  variable  c  is  assigned  the  value  ’1’  in  line  7,  but  in  line  8  it  has  the  value  ’Nn’, 
Once  your  attention  is  drawn  to  this  if  statement,  you  will  probably  realize  that  you  used  the  assignment 
operator  =  in  place  of  the  equal  operator  =  =.  You  can  easily  miss  this  error  during  code  reading. 

FILES 

/usr/lib/ctrace/runtime.c  run-time  trace  package 
SEE  ALSO 

adb(I),  cc(lV),  dbx(l),  tail(l),  ctype(3V),  fclose(3V),  printf(3V),  setjmp(3V),  signal(3V),  string(3) 
DIAGNOSTICS 

This  section  contains  diagnostic  messages  from  both  ctrace  and  cc(lV),  since  the  traced  code  often  gets 
some  cc  warning  messages.  You  can  get  cc  error  messages  in  some  rare  cases,  all  of  which  can  be 
avoided. 

From  ctrace 

warning:  some  variables  are  not  traced  in  this  statement 

Only  10  variables  are  traced  in  a  statement  to  prevent  the  C  compiler  ‘out  of  tree  space;  simplify 
expression*  error.  Use  the  -t  option  to  increase  this  number. 

warning:  statement  too  long  to  trace 

This  statement  is  over  400  characters  long.  Make  sure  that  you  are  using  tabs  to  indent  your  code, 
not  spaces. 
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cannot  handle  preprocessor  code,  use  -P  option 

This  is  usually  caused  by  #ifdef/#endif  preprocessor  statements  in  the  middle  of  a  C  statement,  or 
by  a  semicolon  at  die  end  of  a  #define  preprocessor  statement. 

’  if . . .  else  if’  sequence  too  long 

Split  the  sequence  by  removing  an  else  from  the  middle. 

possible  syntax  error,  try  -P  option 

Use  the  -P  option  to  preprocess  the  ctrace  input,  along  with  any  appropriate  -D,  and  -U 
preprocessor  options.  If  you  still  get  the  error  message,  check  the  WARNINGS  section  below. 

From  cc 

warning:  floating-point  not  implemented 
warning;  illegal  combination  of  pointer  and  integer 
warning;  statement  not  reached 
warning:  sizeof  returns  0 

Ignore  these  messages. 

compiler  takes  size  of  function 

See  the  ctrace  ^possible  syntax  error’  message  above. 

yacc  stack  overflow 

See  the  ctrace  *’if . . .  else  iP  sequence  too  long’  message  above, 
out  of  tree  space;  simplify  expression 

Use  the  -t  option  to  reduce  the  number  of  traced  variables  per  statement  from  the  default  of  10. 
Ignore  the  ‘ctrace:  too  many  variables  to  trace’  warnings  you  will  now  get. 

redeclaration  of  signal 

Either  correct  this  declaration  of  signaI(3V),  or  remove  it  and  #include  <signal.h>. 

Warnings 

You  will  get  a  ctrace  syntax  error  if  you  omit  the  semicolon  at  the  end  of  the  last  element  declaration  in  a 
structure  or  union,  just  before  the  right  brace  ( }).  This  is  optional  in  some  C  compilers. 

Defining  a  function  with  the  same  name  as  a  system  function  may  cause  a  syntax  error  if  the  number  of 
arguments  is  changed.  Just  use  a  different  name. 

ctrace  assumes  that  BADMAG  is  a  preprocessor  macro,  and  that  EOF  and  NULL  are  #deflned  constants. 
Declaring  any  of  these  to  be  variables,  for  example,  ‘int  EOF;’,  will  cause  a  syntax  error. 

BUGS 

ctrace  does  not  know  about  the  components  of  aggregates  like  structures,  unions,  and  arrays.  It  cannot 
choose  a  format  to  print  all  the  components  of  an  aggregate  when  an  assignment  is  made  to  the  entire 
aggregate,  ctrace  may  choose  to  print  the  address  of  an  aggregate  or  use  the  wrong  format  (for  example, 
%e  for  a  structure  with  two  integer  members)  when  printing  the  value  of  an  aggregate. 

Pointer  values  are  always  treated  as  pointers  to  character  strings. 

The  loop  trace  output  elimination  is  done  separately  for  each  file  of  a  multi-file  program.  This  can  result  in 
functions  called  from  a  loop  still  being  trac^,  or  the  elimination  of  trace  output  from  one  function  in  a  file 
until  another  in  the  same  file  is  called. 
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NAME 


cu  -  connect  to  remote  system 


SYNOPSIS 


cu  [  -dhnt  ]  [  -e  I  -o  ]  [  -I  line  ]  [  -s  speed  ]  phone-number 
cu  [  -dh  ]  [  -€  I  -o  ]  [  -s  speed  ]  -I  line 
cu  [  -dh  ]  [  -e  I  -o  ]  systemname 


DESCRIPTION 

cu  calls  up  another  system,  or  possibly  a  terminal.  It  manages  an  interactive  conversation  with  possible 
transfers  of  ASCII  files. 


If  phone-number  is  specified,  it  is  the  telephone  number  of  the  system  to  be  dialed.  Equal  signs  specify  a 
pause  for  a  secondary  dial  tone,  and  minus  signs  specify  dialing  delays  of  4  seconds.  If  systemname  is 
specified,  it  is  the  UUCP  name  of  a  the  system  to  be  dialed;  in  this  case,  cu  will  obtain  an  appropriate  direct 
line  or  telephone  number  from  /etc/uucp/Systems.  Note:  the  systemname  option  should  not  be  used  in 
conjunction  with  the  -I  and  -s  options  as  cu  will  connect  to  the  first  available  line  for  the  system  name 
specified,  ignoring  the  requested  line  and  speed.  If  neither  phone-number  nor  systemname  are  specified, 
the  -1  line  option  must  be  provided;  line  specifies  the  device  name  to  use. 


OPTIONS 

-d 

-h 


-t 

-e 


-o 

-1  line 


-s  speed 


Print  diagnostic  traces. 

Emulate  local  echo,  supporting  calls  to  other  computer  systems  which  expect  terminals  to  be 
set  to  half-duplex  mode. 

For  added  security,  prompt  the  user  to  provide  the  telephone  number  to  be  dialed  rather  than 
taking  it  from  the  command  line. 

Perform  appropriate  mapping  of  RETURN  to  RETURN-LINE-FEED  pairs.  This  is  used  to  dial 
an  ASCn  terminal  which  has  been  set  to  auto  answer. 

Generate  even  parity  for  data  sent  to  the  remote  system. 

Generate  odd  parity  for  data  sent  to  the  remote  system. 

Specify  a  device  name  to  use  as  the  communication  line.  This  can  be  used  to  override  the 
search  that  would  otherwise  take  place  for  the  first  available  line  having  the  right  speed. 
When  the  -1  option  is  used  without  the  -s  option,  the  speed  of  a  line  is  taken  fi'om  the 
/etc/uucp/Devices  file.  When  the  -1  and  -s  options  are  both  used  together,  cu  will  search 
the  Devices  file  to  check  if  the  requested  speed  for  the  requested  line  is  available.  If  so,  the 
connection  will  be  made  at  the  requested  speed;  otherwise  an  error  message  will  be  printed 
and  the  call  will  not  be  made.  The  specified  device  is  generally  a  directly  connected  asyn¬ 
chronous  line  (for  example,  /de\/tiyab)  in  which  case  a  telephone  number  (phone-number) 
is  not  required.  The  specified  device  need  not  be  in  the  /dev  directory.  If  the  specified  dev¬ 
ice  is  associated  with  an  auto  dialer,  a  telephone  number  must  be  provided.  Use  of  this 
option  with  systemname  rather  than  phone-number  will  not  give  the  desired  result  (see  sys¬ 
temname  below). 

Specify  the  transmission  speed  (300,  1200,  2400,  4800,  9600);  The  default  value  is  “Any” 
speed  which  will  depend  on  the  order  of  the  lines  in  the  Devices  file.  Most  modems  are 
either  300  or  1200  baud.  Directly  connected  lines  may  be  set  to  a  speed  higher  than  1200 
baud. 


USAGE 


After  making  the  connection,  cu  runs  as  two  processes:  the  transmit  process  reads  data  from  the  standard 
input  and,  except  for  lines  beginning  with  ",  passes  it  to  the  remote  system;  the  receive  process  accepts  data 
from  the  remote  system  and,  except  for  lines  beginning  with  passes  it  to  the  standard  output.  Normally, 
an  automatic  XON/XOFF  protocol  is  used  to  control  input  from  the  remote  so  the  buffer  is  not  overrun. 
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Commands 

A  tilde  (  )  appearing  as  the  first  character  of  a  line  is  an  escape  signal  which  directs  cu  to  perform  some 
special  action.  The  transmit  recognizes  the  following  escape  sequences: 

Drop  the  connection  and  exit  (you  may  still  be  logged  in  on  the  remote  machine). 

Escape  to  an  interactive  shell  on  the  local  machine  (exiting  the  shell  returns  you  to  cu). 

“Icmd  Run  the  command  cmd  on  the  local  system  (using  sh  -c). 

“%cmd  Run  the  command  cmd  locally  and  send  its  output  to  the  remote  system. 

“%cd  Change  the  directory  on  the  local  system.  Note:  '!cd  will  cause  the  command  to  be  run  by  a 

sub-shell,  probably  not  what  was  intended. 

“%take  from  [to] 

Copy  file/wm  (on  the  remote  system)  to  file  to  on  the  local  system.  If  to  is  omitted,  the 
from  argument  is  used  in  both  places. 

"%put/rowi  [to] 

Copy  file /row  (on  local  system)  to  file  to  on  remote  system.  If  to  is  omitted,  the /row  argu¬ 
ment  is  used  in  both  places. 

For  both  "%take  and  "%put  commands,  as  each  block  of  the  file  is  transferred,  consecutive 
single  digits  are  printed  to  the  terminal. 

""/we  Send  the  line  "line  to  the  remote  system. 

"%break  Send  a  BREAK  to  the  remote  system  (which  can  also  be  specified  as  ”%b). 

‘'%debug  Toggle  the  -d  debugging  option  on  or  off  (which  can  also  be  specified  as "  %d). 

"t  Prints  the  values  of  the  termio(4)  structure  variables  for  the  user’s  terminal  (useful  for 

debugging). 

"1  Prints  the  values  of  the  termio  structure  variables  for  the  remote  communication  line  (useful 

for  debugging). 

"%  nostop  Toggle  between  XON/XOFF  input  control  protocol  and  no  input  control.  This  is  useful  in 
case  the  remote  system  is  one  which  does  not  respond  properly  to  the  XON  or  XOFF  charac¬ 
ters. 

The  receive  process  normally  copies  data  from  the  remote  system  to  its  standard  output.  Internally  the  pro¬ 
gram  accomplishes  this  by  initiating  an  output  diversion  to  a  file  when  a  line  from  the  remote  begins  with ". 

Data  from  the  remote  is  diverted  (or  appended,  if  »  is  used)  to  file  on  the  local  system.  The  trailing  "> 
marks  the  end  of  the  diversion. 

The  use  of  ’’%put  requires  stty(lV)  and  cat(lV)  on  the  remote  side.  It  also  requires  that  the  current  erase 
and  kill  characters  on  the  remote  system  be  identical  to  these  current  control  characters  on  the  local  system. 
Backslashes  are  inserted  at  appropriate  places. 

The  use  of "% take  requires  the  existence  of  echo(l  V)  and  cat(l  V)  on  the  remote  system.  Also,  tabs  mode 
(see  stty(lV))  should  be  set  on  the  remote  system  if  TAB  characters  are  to  be  copied  without  expansion  to 
SPACE  characters. 

When  cu  is  used  on  system  X  to  connect  to  system  Y  and  subsequently  used  on  system  Y  to  connect  to  sys¬ 
tem  Z,  commands  on  system  Y  can  be  executed  by  using  In  general, "  executes  the  command  on  the  ori¬ 
ginal  machine, executes  the  command  on  the  next  machine  in  the  chain. 

EXAMPLES 

To  dial  a  system  whose  telephone  number  is  9  201  555  1212  using  1200  baud  (where  dialtone  is  expected 
after  the  9): 

cu  -sl200  9=12015551212 
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If  the  speed  is  not  specified,  “Any”  is  the  default  value. 

To  login  to  a  system  connected  by  a  direct  line: 
cu  -1  /dev/ttyXX 

or 

cu-lttyXX 

To  dial  a  system  with  the  specific  line  and  a  specific  speed: 
cu  -sl200  -1  ttyXX 

To  dial  a  system  using  a  specific  line  associated  with  an  auto  dialer: 
cu  -1  cuIXX  9=12015551212 

To  use  a  system  name: 

cu  systemname 

FILES 

/etc/uucp/Systems  file  listing  remote  systems 

/etc/uucp/Devices  file  listing  devices  to  use 

/var/spool/Iocks/LCK  . .+  lock  file  to  avoid  conflicts  with  UUCP 

SEE  ALSO 

cat(lV),  echo(lV),  stty(lV),  tip(lC),  uucp(lC),  termio(4) 

DIAGNOSTICS 

Exit  code  is  zero  for  normal  exit,  otherwise,  1. 

WARNINGS 

The  cu  command  does  not  do  any  integrity  checking  on  data  it  transfers.  Data  fields  with  special  cu  char¬ 
acters  may  not  be  transmitted  properly.  Depending  on  the  interconnection  hardware,  it  may  be  necessary 
to  use  a  to  terminate  the  conversion  even  if  stty  0  has  been  used.  Non-printing  characters  are  not 
dependably  transmitted  using  either  the  "%put  or  "%take  commands. 

BUGS 

There  is  an  artificial  slowing  of  transmission  by  cu  during  the  '^%put  operation  so  that  loss  of  data  is 
unlikely. 
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NAME 

cut  -  remove  selected  fields  from  each  line  of  a  file 
SYNOPSIS 

cut  -c  list  [filename  . . .  ] 

cut  -f list  [  “dc  ]  [  -s  ]  [filename  . . .  ] 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

Use  cut  to  cut  out  columns  from  a  table  or  fields  from  each  line  of  a  file;  in  data  base  parlance,  it  imple¬ 
ments  the  projection  of  a  relation.  The  fields  as  specified  by  list  can  be  of  fixed  length,  (such  as  on  a 
punched  card),  or  of  variable  length  between  lines.  They  can  be  marked  with  a  field  delimiter  character, 
such  as  TAB  (as  specified  with  the  -d  option),  cut  can  be  used  as  a  filter;  if  no  files  are  given,  the  standard 
input  is  used.  In  addition,  a  file  name  of  explicitly  refers  to  the  standard  input. 

OPTIONS 

-c  list  By  character  position,  list  is  a  comma-separated  list  of  integer  field  numbers  (in  increasing  order), 
with  an  optional  to  indicate  ranges: 

1,4,7  characters  1, 4  and  7 

1-3,8  characters  1  through  3,  and  8 

-5,10  characters  (1)  through  5,  and  10 
3-  characters  3  through  (last) 

— f  list  By  field  position.  Instead  of  character  positions,  list  specifies  fields  that  are  separated  a  delimiter 
(normally  a  TAB): 

1,4,7  fields  1, 4  and  7 

Lines  with  no  field  delimiters  are  normally  passed  through  intact  (to  allow  for  subheadings). 

— dc  Set  the  field  delimiter  to  c.  The  default  is  a  TAB.  Characters  with  special  meaning  to  the  shell 

such  as  a  TAB  or  SPACE  characters,  must  be  quoted. 

-s  Suppress  lines  with  no  delimiter  characters. 

EXAMPLES 

cut  -d:  -fl,5  /etc/passwd 

Mapping  of  user  IDs  to  names. 

name=who  am  i  |  cut  -fl  -d"  " 

Set  name  to  the  current  login  name. 

SEE  ALSO 

grep(lV),  paste(lV) 

DIAGNOSTICS 

ERROR:  line  too  long 

A  line  can  have  no  more  than  1023  characters  or  fields. 

ERROR:  bad  list  for  c/f  option 

Missing  -c  or  -f  option  or  incorrectly  specified  list.  No  error  occurs  if  a  line  has  fewer 
fields  than  the  list  calls  for. 

ERROR:  no  fields 

The  list  is  empty. 

ERROR:  no  delimiter 

Missing  char  on  -d  option. 

ERROR:  cannot  handle  multiple  adjacent  backspaces 

Adjacent  backspaces  cannot  be  processed  correcdy. 
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WARNING:  cannot  open  filename:  reason 

filename  cannot  be  read  or  does  not  exist.  If  multiple  filenames  are  present,  process- 
ing  continues. 

WARNING:  I/O  error  residmg  filename:  reason 

An  I/O  error  occurred  when  reading  filename .  If  multiple  filenames  are  present,  processing 
continues. 
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NAME 

cxref-  generate  a  C  program  cross-reference 


SYNOPSIS 

cxref  [  -c  ]  [  — w  [  num  ]  ]  [  -o  filename  ]  [  -t  ]  filenames 
SYSTEM  V  SYNOPSIS 

/usr/Sbin/cxref  [  -c  ]  [  -w  [  num  ]  ]  [  -o  filename  ]  [  -t  ]  filenames 
AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

cxref  analyzes  a  collection  of  C  files  and  attempts  to  build  a  cross-reference  table,  cxref  utilizes  a  special 
option  of  cpp(l)  to  include  #define’d  information  in  its  symbol  table.  It  produces  a  listing  on  standard  out¬ 
put  of  all  symbols  (auto,  static,  and  global)  in  each  file  separately,  or  with  the  -c  option,  in  combination. 
Each  symbol  contains  an  asterisk  (♦)  before  the  declaring  reference. 

SYSTEM  V  DESCRIPTION 

The  System  V  version  of  cxref,  run  as  /usr/Sbin/cxref,  makes  the  C  preprocessor  search  for  include  files  in 
/usr/Sinclude  before  searching  for  them  in  /usr/nnclude. 


OPTIONS 


In  addition  to  the  -D,  -I  and  -U  options  (which  are  identical  to  their  interpretation  by  cc(lV)),  the  follow¬ 
ing  options  are  interpreted  by  cxref: 


-c 

-w[  num  ] 

-o  filename 
-s 

-t 


Print  a  combined  cross-reference  of  all  input  files. 

Width  option  which  formats  output  no  wider  than  num  (decimal)  columns.  This  option  will 
default  to  80  if  num  is  not  specified  or  is  less  than  51. 

Direct  output  to  named  file. 

Operate  silently;  does  not  print  input  file  names. 

Format  listing  for  80-column  width. 


FILES 

/usr/tmp/xr^ 

temporary  files 


SEE  ALSO 

cc(lV),  cpp(l) 


DIAGNOSTICS 

Error  messages  are  unusually  cryptic,  but  usually  mean  that  you  cannot  compile  these  files,  anyway. 

NOTES 

While  the  compiler  allows  8-bit  strings  and  comments,  8-bits  are  not  allowed  anywhere  else.  See  cc(lV) 
for  an  explanation  about  why  cc  is  not  8-bit  clean. 

BUGS 

cxref  considers  a  formal  argument  in  a  #define  macro  definition  to  be  a  declaration  of  that  symbol.  For 
example,  a  program  that  #includes  ctype.  h,  will  contain  many  declarations  of  the  variable  c. 
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NAME 

date  -  display  or  set  the  date 

SYNOPSIS 

date  [  -u }  [  -a  [  -  ]  sss.:ff]  [yymmddhhmm[.ss]][  ^format  ] 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/date  [  -u  ]  [  -a  [  -  ]  ]  [  mmddhhmm  [ yy  ]  ]  [  +format  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

If  no  argument  is  given,  or  if  the  argument  begins  with  +,  date  displays  the  current  date  and  time.  Other¬ 
wise,  the  current  date  is  set.  Only  the  super-user  may  set  the  date. 

yy  is  the  last  two  digits  of  the  year;  the  first  mm  is  the  month  number;  dd  is  the  day  number  in  the  month;  hh 
is  the  hour  number  (24  hour  system);  the  second  mm  is  the  minute  number;  .ss  (optional)  specifies  seconds. 
The  year,  month  and  day  may  be  omitted;  the  current  values  are  supplied  as  defaults. 

If  the  argument  begins  with  +,  the  output  of  date  is  under  the  control  of  the  user.  The  format  for  the  output 
is  similar  to  that  of  the  first  argument  to  printf(3V).  All  output  fields  are  of  fixed  size  (zero  padded  if 
necessary).  Each  field  descriptor  is  preceded  by  %  and  will  be  replaced  in  the  output  by  its  corresponding 
value.  A  single  %  is  encoded  by  %%.  All  other  characters  are  copied  to  the  output  without  change.  The 
string  is  always  terminated  with  a  new-line  character. 

Field  Descriptors: 

n  insert  a  new-line  character 

t  insert  a  tab  character 

m  month  of  year  -  01  to  12 
d  day  of  month  -  01  to  3 1 
y  last  2  digits  of  year  -  00  to  99 
D  date  as  mm/dd/yy 

H  hour  -  00  to  23 

M  minute  -  00  to  59 

S  second  -  00  to  59 

T  time  as  HH:MM:SS 

j  day  of  year  -  001  to  366 
w  day  of  week  -  Sunday  =  0 
a  abbreviated  weekday  -  Sun  to  Sat 
h  abbreviated  month  -  Jan  to  Dec 
r  time  in  AM/PM  notation 

SYSTEM  V  SYNOPSIS 

When  setting  the  date,  the  first  mm  is  the  month  number;  dd  is  the  day  number  in  the  month;  hh  is  the  hour 
number  (24  hour  system);  the  second  mm  is  the  minute  number;  yy  is  the  last  2  digits  of  the  year  number 
and  is  optional.  The  current  year  is  the  default  if  no  year  is  mentioned. 

OPTIONS 

-u  Display  the  date  in  GMT  (universal  time).  The  system  operates  in  GMT;  date  normally 

takes  care  of  the  conversion  to  and  from  local  standard  and  daylight  time,  -u  may  also  be 
used  to  set  GMT  time. 

-a  [-'Isss.jff  Using  the  adjtiTne(2)  system  call,  tell  the  system  to  slowly  adjust  the  time  by  sss.fff 
seconds  (///represents  fractions  of  a  second).  This  adjustment  can  be  positive  or  nega¬ 
tive.  The  system’s  clock  will  be  sped  up  or  slowed  down  until  it  has  drifted  by  the  number 
of  seconds  specified. 
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EXAMPLES 

date  10080045 

Would  set  the  date  to  Oct  8, 12:45  AM. 

If  the  year  were  1986,  and  the  date  were  so  set, 
date  '+DATE:  %m/%d/%y%nTIME: 

would  generate  as  output: 

DATE:  08/01/86 
TIME:  14:45:05 

FILES 

/var/adm/wtmp  to  record  time-setting 

/usr/share/lib/zoneinfo  timezone  definitions 
SEE  ALSO 

adjtime(2),  printf(3V),  utmp(5V) 

DIAGNOSTICS 

date:  Failed  to  set  date:  Not  owner 

If  you  try  to  change  the  date  but  are  not  the  super-user. 

date:  bad  format  character 

If  the  field  descriptor  is  not  recognizable. 
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NAME 

dbx  •“  source-level  debugger 
SYNOPSIS 

dbx  [  -f /count  ]  [  -i  ]  [  -I  ]  [  -k  ]  [  -kbd  ]  [  -P/d  ]  [  -r  ]  [  -s  startup  ]  [  -sr  tstartup  ] 

[  objjile  [  corefile  I  process-id  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  Debugging  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

dbx  is  a  utility  for  source-level  debugging  and  execution  of  programs  written  in  C,  or  other  supported 
languages  such  as  Pascal  and  FORTRAN  77.  dbx  accepts  the  same  commands  as  dbxtool(l),  but  uses  a 
standard  terminal  (tty)  interface. 

objfile  is  an  object  file,  produced  by  cc(lV)  or  another  compiler,  with  the  -g  option  to  include  a  symbol 
table.  This  symbol  table  contains  the  names  of  all  the  source  files  used  to  create  it,  and  these  files  are  avail¬ 
able  for  perusal  while  using  the  debugger. 

If  no  objfile  is  specified,  you  can  use  dbx"s  debug  command  to  specify  the  program  to  debug. 

If  there  is  a  file  named  core  in  the  current  directory,  or  a  corefile  argument  is  specified,  you  can  use  dbx  to 
examine  the  state  of  the  program  when  the  core  file  was  produced. 

dbx  commands  in  the  file  ,  dbxinit  are  executed  immediately  before  the  symbol  table  is  read,  if  that  file 
exists  in  the  current  directory,  or  in  the  user’s  home  directory  if  .dbxinit  does  not  exist  in  the  current  direc- 
tOTy. 

OPTIONS 

-f /count 

— i 

-I  dir 

-k 
-kbd 

-Vfd 

-r 


-s  startup 
-sr  tstartup 


Alter  the  initial  estimate  of  the  number  functions  in  the  program  being  debugged.  The  ini¬ 
tial  setting  is  500. 

Force  dbx  to  act  as  though  the  standard  input  were  a  terminal  or  terminal  emulator. 

Add  dir  to  the  list  of  directories  in  which  to  search  for  a  source  file,  dbx  normally  searches 
the  current  directory,  and  the  directory  where  objfile  is  located.  The  directory  search  path 
can  be  reset  with  the  use  command. 

Kernel  debugging. 

Debug  a  program  that  sets  the  keyboard  into  up-down  translation  mode.  This  flag  is  neces¬ 
sary  if  a  program  uses  up-down  decoding. 

Create  a  pipeline  to  a  dbxtool(l)  process,  /d  is  the  file  descriptor  through  which  to  pipe  out¬ 
put  to  the  ffont-end  process.  This  option  is  passed  automatically  to  dbx  by  dbxtool. 

Execute  objfile  immediately.  Parameters  follow  the  object  file  name  (redirection  is  handled 
properly).  If  the  program  terminates  successfully,  dbx  exits.  Otherwise,  dbx  reports  the 
reason  for  termination  and  waits  for  a  response,  dbx  reads  from  the  terminal  (/dev/tty) 
when  -r  is  specified  and  standard  input  is  a  file  or  pipe. 

Read  initialization  commands  from  the  file  named  startup. 

Read  initialization  commands  from  the  temporary  file  named  startup,  and  then  remove  that 
file. 


USAGE 

Refer  to  dbx  in  the  Debugging  Tools  manual. 

The  most  useful  basic  commands  to  know  about  are  run,  to  run  the  program  being  debugged,  where,  to 
obtain  a  stack  trace  with  line  numbers,  print,  to  display  variables,  and  stop,  to  set  breakpoints. 
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Filenames 

Filenames  in  dbx  may  include  shell  metacharacters.  The  shell  used  for  pattern  matching  is  determined  by 
the  SHELL  environment  variable. 


Expressions 

dbx  expressions  are  combinations  of  variables,  constants,  procedure  calls,  and  operators.  Variables  are 
either  variables  in  the  program  being  debugged  or  special  dbx  variables  whose  names  begin  with  $.  Hexa¬ 
decimal  constants  must  be  preceded  by  a  ‘Ox’  and  octal  constants  by  a  ‘O’.  Character  constants  must  be 
enclosed  in  single  quotes.  Expressions  cannot  involve  strings,  structures,  or  arrays,  although  elements  of 
structures  or  arrays  may  be  used. 


Operators 
+  —  * 


f  div  % 


«  >> 

&  ♦ 

<  >  <= 


& 


t-  » 


Add,  subtract,  multiply,  divide,  integer  division,  and  remainder,  respectively. 

dbx  has  two  division  operators.  ‘/’  always  yields  a  floating-point  result  and 
div  always  yields  an  integral  result. 

Left-shift,  right-shift,  bitwise  AND,  bitwise  OR,  and  bitwise  complement. 
Address  of  operator,  and  contents  of  operator. 

Less  than,  greater  than,  less  than  or  equal  to,  greater  than  or  equal  to,  equal, 
not  equal,  and  negation. 

Logical  AND,  and  logical  OR 

Size  of  variable  or  type  and  type  cast. 

Field  reference,  and  pointed-to-field  reference  (however,  dot  works  for  lx)lh 
in  dbx). 

Precedence  and  associativity  of  operators  are  the  same  as  for  C;  parentheses  can  be  used  for  grouping. 

If  there  is  no  corefile,  only  expressions  containing  constants  are  available.  Procedure  calls  require  an 
active  child  process. 


&&  II 
sizeof  (cast) 
.  -~> 


Scope  Rules 

dbx  uses  the  current  file  and  function  to  resolve  scope  conflicts.  Their  values  are  updated  as  files  and  func¬ 
tions  are  entered  and  exited  during  execution.  You  can  also  change  them  explicitly  by  using  the  file  and 
func  commands.  When  the  current  function  is  changed,  the  current  file  is  updated  along  with  it,  but  not 
vice  versa. 


Execution  and  Tracing  Commands 

"'C  Interrupt.  Stop  the  program  being  debugged  and  enter  dbx. 
run  [  args  ]  [  <  infile  ]  [  >  I  »  outfile  ] 

Start  executing  objfile,  reading  in  any  new  information  from  it.  With  no  args,  use  the  argument 
list  from  the  previous  run  command. 

args  Pass  args  as  command-line  arguments  to  the  program. 

<  I  >  I »  Redirect  input  or  output,  or  append  output  to  a  file. 

rerun  [  args  ]  [  <  infile  ]  [  >  I  »  outfile  ] 

Like  the  run  command,  except  that  when  args  are  omitted,  none  are  passed  to  the  program. 

cont  [  at  sourceline  ]  [  sig  signal  ] 

Continue  execution  from  where  it  stopped. 

at  sourceline  Start  from  sourceline 

sig  signal  Continue  as  if  signal  had  occurred,  signal  may  be  a  number  or  a  name  as 
with  catch. 
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trace  [  m  function  ]  [  if  condition  ] 
trace  sourceline  [  if  condition  ] 
trace  function  [  if  condition  ] 
trace  expression  at  sourceline  [  if  condition  ] 
trace  variable  [  in  function  ]  [  if  condition  ] 

Display  tracing  information.  If  no  argument  is  specified,  each  source  line  is  displayed  before  exe¬ 
cution.  Tracing  is  turned  off  when  the  function  or  procedure  is  exited. 

In  function  Display  tracing  information  only  while  executing  the  function  or  pro¬ 

cedure /wncriow. 

if  condition  Display  tracing  information  only  if  condition  is  true. 
sourceline  Display  the  line  immediately  prior  to  executing  it.  Source  line-numbers 
from  another  file  are  written  asfilename:n, 

function  Display  the  routine  and  source  line  called  from,  parameters  passed  in,  and 
return  value. 
expression  at  sourceline 

Display  the  value  of  expression  whenever  sourceline  is  reached. 
variable  Display  the  name  and  value  whenever  variable  changes. 

stop  at  sourceline  [  if  condition  ] 
stop  \n  function  [  if  condition  ] 
stop  variable  [  if  condition  ] 
stop  if  condition 

Stop  execution  when  the  sourceline  is  reached,  function  is  called,  variable  is  changed,  or  condi¬ 
tion  becomes  true. 

when  in  function  {  command  ;  [  command 
when  at  sourceline  {  command  ;  [  command ;]...} 
when  condition  {  command  ;  [  command  ;]...} 

Execute  the  dbx  commandos)  function  is  called,  sourceline  is  reached,  or  condition  is  true. 

status  [  >  filename  ] 

Display  active  trace,  stop  and  when  commands,  and  associated  command  numbers, 
delete  all 

delete  cmd-no  [ ,  cmd-no  ] . . . 

Remove  all  traces,  stops  and  whens,  or  those  corresponding  to  each  dbx  cmd-no  (as  displayed  by 
status). 

clear  [  source  line] 

Clear  all  breakpoints  at  the  current  stopping  point,  or  at  sourceline. 
catch  [  signal  [ ,  signal  ] . . .  ] 

Display  all  signals  currently  being  caught,  or  catch  signal  before  it  is  sent  to  the  program  being 
debugged.  A  signal  can  be  specified  either  by  name  (with  the  SIG  prefix  omitted,  as  with  kill(l)) 
or  number.  Initially  all  signals  are  caught  except  SIGHUP,  SIGEMT,  SIGFPE,  SIGKILL,  SIGALRM, 
SIGTSTP,  SIGCONT,  SIGCHLD,  and  SIGWINCH. 

ignore  [  signal  [ ,  signal  ]  . . .  ] 

Display  all  signals  currently  being  ignored,  or  stop  catching  signal^  which  may  be  specified  by 
name  or  number  as  with  catch. 

step  [/i] 

Execute  the  next  n  source  lines.  If  omitted,  n  is  taken  to  be  1 .  Steps  into  functions. 

next  [n  ] 

Execute  the  next  n  source  lines.  If  omitted,  n  is  taken  to  be  1.  next  steps  past  functions. 
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Naming,  Printing  and  Displaying  Data 

Variables  from  another  function  or  procedure  with  the  same  name  as  one  in  the  current  block  must  be 
qualified  as  follows: 

{'  sour  cefde  ']function  'variable 

For  Pascal  variables  there  may  be  more  than  one  function  or  procedure  name,  each  separated  by  a 
backquote. 

print  expression  [ ,  expression  ]  ... 

Print  the  value  of  each  expression,  which  may  involve  function  calls.  Program  execution  halts 
when  a  breakpoint  is  reached,  and  dbx  resumes. 

display  [  expression  [ ,  expression  ] . . .  ] 

Print  a  list  of  the  expressions  currently  being  displayed,  or  display  the  value  of  each  expression 
whenever  execution  stops. 

undisplay  [  expression  [ ,  expression  ] . . .  ] 

Stop  displaying  the  value  of  each  expression  whenever  execution  stops.  If  expression  is  a  con¬ 
stant,  it  refers  to  a  display-number  as  shown  by  the  display  command  with  no  arguments. 

whatis  identifier 
whatis  type 

Print  the  declaration  of  the  given  identifier  or  type,  types  are  useful  to  print  all  the  members  of  a 
structure,  union,  or  enumerated  type. 

which  identifier 

Print  the  fully-qualified  name  of  the  given  identifier, 
whereis  identifier 

Print  the  fully  qualified  name  of  all  symbols  matching  identifier. 

assign  variable  =  expression 
set  variable  -  expression 

Assign  the  value  of  expression  to  variable.  There  is  no  type  conversion  for  operands  of  differing 
type. 

s^i%lfpr€g-wordl  word2  wordS 

Treat  the  concatenation  of  wordl  word2  wordS  as  a  96-bit,  IEEE  floating-point  value  and  assign  it 
to  the  MC6888 1  floating-point  register  fpreg.  (Supported  only  on  Sun-3). 

call  functioniparameters) 

Execute  the  named  function.  Arguments  are  passed  according  to  the  rules  for  the  source-language 
oifunction. 

where  [  n] 

List  all,  or  the  top  n,  active  functions  on  the  stack, 
dump  [Junction  ] 

Display  the  names  and  values  of  local  variables  and  parameters  in  the  current  or  specified /mwc- 
tion. 

up  [/i] 
down  [n] 

Move  up  (towards  “main’*)  or  down  the  call  stack,  one  or  n  levels. 

File  Access  Commands 

edit  [filename  {function  ] 

Edit  the  current  source  file,  or  the  given  filename  or  the  file  that  contains  function. 
file  [filename  ] 

Print  the  name  of  the  current  source  file,  or  change  the  current  source  file  \o  filename. 
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func  [functionl program  I  objfile  ] 

Print  the  name  of  the  cuirent  function,  or  change  to  the  gwen  function,  program,  or  objfile.  Also 
changes  the  current  scope. 

list  [  startline  [ ,  endline  ]  ] 
list  function 

List  the  next  ten  lines  from  current  source  file,  list  from  startline  through  endline,  or  and  list  from 
five  lines  above,  to  five  lines  below  the  first  line  oi function. 

use  [  directory-list  ] 

Print  or  set  the  list  of  directories  in  which  to  search  for  source  files, 
cd  [  directory  ] 

Change  the  current  working  directory  for  dbx  to  directory  (or  to  the  value  of  the  HOME  environ¬ 
ment  variable). 

pwd  Print  the  current  working  directory  for  dbx. 

freg-exp[l] 

Ireg-exp  [?] 

Search  the  current  file  for  the  regular  expression  reg-exp,  from  the  next  (previous)  line  to  the  end 
(top).  The  matching  line  becomes  the  new  current  line. 

Miscellaneous  Commands 
sh  command-line 

Pass  the  command  line  to  the  shell  for  execution.  The  SHELL  environment  variable  determines 
which  shell  is  used. 

alias  new-command-name  character-sequence 

Respond  to  new-command-name  as  though  it  were  character-sequence.  Special  characters  occur¬ 
ring  in  character-sequence  must  be  enclosed  in  quotation  marks.  Alias  substitution  as  with  the  C 
shell  (csh(l))  also  occurs. 

help  [  command  ] 

Display  a  synopsis  of  dbx  commands,  or  print  a  short  message  explaining  command. 

make  Invoke  make(l)  with  the  name  of  the  program  as  its  argument.  Any  arguments  set  using  dbxenv 
makeargs  are  also  passed  as  arguments. 

setenv  name  string 

Set  environment  variable  name  to  string. 
source  filename 

Read  and  execute  dbx  commands  from  filename.  Useful  when  the  filename  has  been  created  by 
redirecting  an  earlier  status  command. 

quit  Exit  dbx. 

dbxenv 

dbxenv  case  sensitive  I  insensitive 
dbxenv  fpaasm  on  i  off 
dbxenv  fp abase  a  [0-7]  I  off 

dbxenv  makeargs  string 
dbxenv  stringlen  num 
dbxenv  speed  seconds 

Display  dbx  attributes  or  set  the  named  attribute: 

case  Controls  whether  upper-  and  lower-case  characters  are  treated  as  different 
values.  The  default  is  sensitive. 

fpaasm  Controls  FPA  instruction  disassembly.  The  default  is  on.  (Supported  only 
on  Sun-3). 
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fpabase  Sets  the  base  register  for  FPA  instruction  disassembly.  The  default  is  off. 
(Supported  only  on  Sun-3  systems). 

makeargs  Sets  arguments  to  pass  to  make.  The  default  is  CC=cc -g. 
speed  Set  the  interval  between  execution  during  tracing.  The  default  is  0.5 
seconds. 

stringlen  Controls  the  maximum  number  of  characters  printed  for  a  ‘  ‘char  *”  variable 
in  a  C  program.  The  default  is  512. 

debug  [  -k  ]  [  objfile  [  corefile  I  pid  ]  ] 

With  no  arguments,  print  the  name  of  the  current  program.  With  arguments,  stop  debugging  the 
current  program  and  begin  debugging  objfile  having  either  corefile  or  the  current  process  ID  pid. 
The  -k  option  indicates  kernel  debugging. 

kill  Stop  debugging  of  the  current  program,  but  be  ready  to  debug  another. 

detach  Detach  the  current  program  (process)  from  dbx.  dbx  will  be  unable  to  access  or  modify  its  state, 
modules 

modules  select  [  all  I  objfile  . . .  ] 
modules  append  objfile  [  objfile  . . .  ] 

The  modules  command  displays  or  sets  the  current  modules  selection  list.  If  the  modules  selec¬ 
tion  list  is  set,  the  debugger  reads  debugging  information  only  for  object  files  in  this  list.  Debug¬ 
ging  information  for  object  files  not  in  the  modules  selection  list  is  ignored. 

modules  with  no  arguments  displays  the  set  of  object  files  for  which  source  level  debugging  infor¬ 
mation  is  currently  available,  including  the  path  names  of  any  associated  source  files.  If  the 
debugger  cannot  access  a  source  file  for  which  it  has  debugging  information,  it  displays  the  source 
file  name  with  a  trailing  *?’  (question  mark)  character.  Source  file  path  names  reflect  the  current 
search  path  as  set  by  the  use  command  or  the  ~I  option. 

modules  select  displays  the  current  modules  selection  list  if  no  objfile  is  given.  Otherwise, 
modules  select  sets  the  modules  selection  list  to  the  specified  object  files.  To  get  complete  debug¬ 
ging  information,  the  debugger  may  need  to  read  object  files  not  in  the  modules  selection  list, 
‘modules  select’  displays  these  “implied”  file  names  with  trailing  (asterisk)  characters  (see 
NOTES),  ‘modules  select  all’  discards  the  modules  selection  list. 

modules  append  appends  the  specified  object  files  to  the  modules  selection  list. 

If  the  modules  selection  list  includes  an  object  file  not  in  the  executable  being  debugged,  the 
debugger  issues  a  warning. 

proc  [  pid  ] 

For  kernel  debugging.  Display  which  process  is  mapped  into  the  user  area,  or  map  pid  to  the  user 
area. 


Machine-Level  Commands 

trace!  [  address  ]  [  if  condition  ] 

trace!  [  variable  ]  [at  address  ]  [  if  condition  ] 

Trace  execution  of  a  specific  machine-instruction  address. 

stop!  [  variable  ]  [  if  condition  ] 
stop!  [at  address  ]  [  if  condition  ] 

Set  a  breakpoint  at  a  machine  instruction  address. 

step! 

next!  Single  step  as  in  step  or  next,  but  do  a  single  machine  instruction  rather  than  a  source  line. 
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address,  address  /  [  mode  ] 
address  /  [codnt  ]  [  mode  ] 

Display  the  contents  of  memory  starting  at  the  first  (or  current)  address  up  to  the  second  address, 
or  until  count  items  have  been  displayed.  The  initial  display  mode  is  X.  The  following  modes  are 
supported: 

i  the  machine  instruction 

d  word  in  decimal 

D  longword  in  decimal 

o  word  in  octal 

O  longword  in  octal 

X  word  in  hexadecimal 

X  longword  in  hexadecimal 

b  byte  in  octal 

c  byte  as  a  character 

s  strings  as  characters  terminated  by  a  null 

f  single  precision  real  number 

F  double-precision  real  number 

E  extended-precision  real  number  (not  supported  on  Sun-4) 

An  address  can  be  specified  as  an  item  from  the  following  list,  as  an  expression  made  up  of  other 
addresses  and  the  operators  *+’,  ‘+’,  and  indirection  (unary  ‘**),  or  as  an  arbitrary  expression 

enclosed  in  parentheses. 

&name  symbolic  address 

integer  numeric  address 

address  =  [  mode  ] 

Display  the  value  of  the  address. 

Machine  Registers 

The  machine  registers  for  the  current  machine  type  are  represented  as  special  dbx  variables.  They  can  be 
used  in  expressions  as  any  other  dbx  variable  can.  The  registers  and  their  variable  names  are: 

Sun-2  and  Sun-3  Registers 


$(J[0-7] 

data  registers 

$a[0-7] 

address  registers 

$rp 

frame  pointer,  equivalent  to  register  a6 

$sp 

stack  pointer,  equivalent  to  register  a7 

$pc 

program  counter 

$ps 

program  status 

Sun-3-OnIy  Registers 

$fp[0-7] 

MC6888 1  data  registers 

$fpc 

MC68881  control  register 

$fps 

MC68881  status  register 

$fpi 

MC68881  instruction  address  register 

$fpf 

MC68881  flags  register  (unused,  idle,  busy) 

$fpa[0-31] 

double-precision  interpretation  of  FPA  registers, 

$sfpa[0-31] 

single-precision  interpretation  of  FPA  registers. 

Sun-4  Registers 

$g[0-7] 

global  registers 

$o[0-7] 

“out”  registers 

$i[0-7] 

“in”  registers 

$l[0-7] 

“local”  registers 

$fp 

frame  pointer,  equivalent  to  register  i6 

$sp 

stack  pointer,  equivalent  to  register  o6 
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$y 

Y  register 

$psr 

processor  state  register 

Swim 

window  invalid  mask  register 

$tbr 

trap  base  register 

$pc 

program  counter 

$npc 

next  program  counter 

$f[0-31] 

FPU  “f”  registers 

$fsr 

FPU  status  register 

$fq 

FPU  queue 

Sun386i  Registers 

$ss 

stack  segment  register 

$eflags 

flags 

$cs 

code  segment  register 

$eip 

instruction  pointer 

$eax 

general  register 

$ecx 

general  register 

$edx 

general  register 

$ebx 

general  register 

$esp 

stack  pointer 

$ebp 

frame  pointer 

$esi 

source  index  register 

$edi 

destination  index  register 

$ds 

data  segment  register 

$es 

alternate  data  segment  register 

$fs 

alternate  data  segment  register 

$gs 

alternate  data  segment  register 

Registers  for  the  80386  lower  halves  (16  bits)  are: 

$ax 

general  register 

$cx 

general  register 

$dx 

general  register 

$bx 

general  register 

$sp 

stack  pointer 

$bp 

frame  pointer 

$si 

source  index  register 

$di 

destination  index  register 

$ip 

instruction  pointer,  lower  16  bits 

$flags 

flags,  lower  16  bits 

The  first  four  Sun386i  16-bit  registers  can  be  split  into  8-bit  parts: 

$al  lower  (right)  half  of  register  $ax 

$ah  higher  (left)  half  of  register  $ax 

$cl  lower  (right)  half  of  register  $cx 

$ch  higher  (left)  half  of  register  $cx 

$dl  lower  (right)  half  of  register  $dx 

$dh  higher  (left)  half  of  register  Sdx 

$bl  lower  (right)  half  of  register  $bx 

$bh  higher  (left)  half  of  register  $bx 

Registers  for  the  80387  are: 

$fctrl  control  register 

$fstat  status  register 

$ftag  tag  register 

$fip  instruction  pointer  offset 

$fcs  code  segment  selector 


/  ^ 
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$fopoiT  operand  pointer  offset 

$fopsel  operand  pointer  selector 

$stO  -  $st7  data  registers 

ENVIRONMENT 

dbx  checks  the  environment  variable  EDITOR  for  the  name  of  the  text  editor  to  use  with  the  edit  command. 

FILES 

core  default  core  file 

.  dbxinit  local  dbx  initialization  file 

7.  dbxinit  user’s  dbx  initialization  file 

SEE  ALSO 

cc(lV),  csh(l),  dbxtool(l),  kill(l),  lex(l),  make(l),  yacc(l) 

Debugging  Tools 

NOTES 

Because  the  cc  command  does  not  generate  or  support  8-bit  symbol  names,  it  is  inappropriate  to  make  dbx 
8-bit  clean.  See  cc(l  V)  for  an  explanation  about  why  cc  is  not  8-bit  clean. 

To  save  space,  the  linker  eliminates  debugging  information  redundantly  defined  in  multiple  include  files.  If 
the  linker  excluded  some  of  the  symbols  for  an  object  file  in  the  modules  selection  list,  the  debugger  must 
read  debugging  information  from  the  object  files  where  these  symbols  were  first  defined.  If  these 
“implied”  modules  are  not  in  the  modules  selection  list,  ‘modules  select’  displays  their  names  with  trailing 
(asterisk)  characters. 

BUGS 

dbx  does  not  correctly  handle  C  variables  that  are  local  to  compound  statements.  When  printing  these 
variables  it  often  gives  incorrect  results. 

dbx  does  not  handle  FORTRAN  entry  points  well  —  it  treats  them  as  if  they  were  independent  routines, 
dbx  does  not  handle  assigning  to  FORTRAN  complex  types  correctly  (see  the  assign/set  command). 

Unlike  C,  dbx  does  not  recognize  an  array  or  function  name  as  the  address  of  the  array  or  function.  In 
dbx,  an  array  name  signifies  the  entire  array,  and  a  function  name  signifies  a  call  to  the  function  with  no 
arguments.  To  get  the  address  of  an  array,  take  the  address  of  its  first  element.  To  get  the  address  of  a 
function,  take  the  address  of  its  name. 

Casts  do  not  work  with  FORTRAN  77  or  Pascal. 

Executable  code  incorporated  into  a  source  file  using  an  ^include  preprocessor  directive  confuses  dbx. 
dbx  is  confused  by  the  output  of  program  generators  such  as  yacc(l)  and  lex(l). 

A  step  command  issued  at  a  procedure  call  will  not  work  properly  when  debugging  information  is  available 
for  the  function  being  called  and  that  function  is  in  a  shared  library. 
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NAME 

dbxtool  -  SunView  interface  for  the  dbx  source-level  debugger 
SYNOPSIS 

dbxtool  [  -d  1  [  -i  ]  [  — k  ]  [  -kbd  ]  [  —I  directory  ]  [  objectfile  [  corefile  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  Debugging  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

dbxtool,  a  source-level  debugger  for  C,  Pascal  and  FORTRAN  77  programs,  is  a  standard  tool  that  runs 
within  the  SunView  environment.  It  accepts  the  same  commands  as  dbx,  but  provides  a  more  convenient 
user  interface. 

You  can  use  the  mouse  to  set  breakpoints,  examine  the  values  of  variables,  control  execution,  peruse 
source  files,  and  so  on.  dbxtool  has  separate  subwindows  for  viewing  source  code,  entering  commands 
and  other  uses. 

objectfile  is  an  object  file  produced  by  cc(lV),  any  other  Sun  compiler,  (or  a  combination  of  them)  with  the 
appropriate  flag  (-g)  specified  to  produce  symbol  information  in  the  object  file.  IMPORTANT:  every  stage 
of  the  compilation  process,  including  the  linking  phase,  must  include  the  -g  option.  If  no  objectfile  is 
specified,  you  can  use  the  debug  command  to  specify  the  program  to  be  debugged.  The  object  file  contains 
a  symbol  table  which  includes  the  names  of  all  the  source  files  translated  by  the  compiler  to  create  it. 
These  files  are  available  for  perusal  while  using  the  debugger. 

If  a  file  named  core  exists  in  the  current  directory  or  a  corefile  is  specified,  dbxtool  can  be  used  to  examine 
the  state  of  the  program  when  it  faulted. 

Debugger  commands  in  the  file  .  dbxinit  are  executed  immediately  after  the  symbolic  information  is  read, 
if  that  file  exists  in  the  current  directory,  or  in  the  user’s  home  directory  if  .dbxinit  does  not  exist  in  the 
current  directory. 

OPTIONS 

-d  Produce  debugging  information  for  the  pipeline  from  which  it  reads  dbx(l)  output. 

-i  Force  dbxtool  to  act  as  though  standard  input  were  a  terminal. 

-k  Kernel  debugging. 

-kbd  Debugs  a  program  that  sets  the  keyboard  into  up/down  translation  mode.  This  flag  is  necessary  if 
you  are  debugging  a  program  that  uses  up/down  encoding. 

-I  directory 

Add  directory  to  the  list  of  directories  that  are  searched  when  looking  for  a  source  file.  Normally 
dbxtool  looks  for  source  files  in  the  current  directory  and  then  in  the  directory  where  objectfile  is 
located.  The  directory  search  path  can  also  be  set  with  the  use  command.  Multiple  -I  options 
may  be  given. 

USAGE 

Refer  to  dbx(l)  for  a  summary  of  dbx  commands,  or  Debugging  Tools  for  more  complete  information  on 
using  dbxtool. 

FILES 

core  default  core  file 

.  dbxinit  local  dbx  initialization  file 

7.  dbxinit  user’s  dbx  initialization  file 

SEE  ALSO 

cc(lV),  dbx(l) 

Debugging  Tools 
SunView  Programmer  s  Guide 
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BUGS 

The  bugs  for  dbx(l)  apply  to  dbxtool  as  well. 

The  interaction  between  scrolling  in  the  source  subwindow  and  dbx’s  regular  expression  search  commands 
is  wrong.  Scrolling  should  affect  where  the  next  search  begins,  but  it  does  not. 
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NAME 

dc  -  desk  calculator 

SYNOPSIS 

dc  [filename  ] 

DESCRIPTION 

dc  is  an  arbitrary  precision  arithmetic  package.  Ordinarily  it  operates  on  decimal  integers,  but  an  input 
base,  output  base,  and  a  number  of  fractional  digits  to  be  maintained  may  be  specified.  The  overall  struc¬ 
ture  of  dc  is  a  stacking  (reverse  Polish)  calculator.  If  an  argument  is  given,  input  is  taken  from  that  file 
until  its  end,  and  then  from  the  standard  input. 

Note:  bc(l)  is  a  preprocessor  for  dc  that  provides  infix  (normal  arithmetic)  notation,  a  C-like  syntax  for 
functions,  and  reasonable  control  structures  for  programs. 

The  following  input  constructs  are  recognized: 

Commands 

number  Push  a  number  onto  the  stack.  A  number  is  an  unbroken  string  of  the  digits  0-9.  It  may  be 
preceded  by  an  underscore  to  input  a  negative  number,  and  may  contain  decimal  points. 

+  — /  *  %  " 

The  top  two  values  on  the  stack  are:  added  (+),  subtracted  (-),  multiplied  (*),  divided  (/), 
remaindered  (%),  or  exponentiated  C).  The  two  entries  are  popped  off  the  stack  and  the  result 
is  pushed  in  their  place.  Any  fractional  part  of  an  exponent  is  ignored. 

sx  Pop  the  top  of  the  stack  and  store  into  a  register  named  x,  where  x  is  any  character. 

S  X  Treat  x  as  a  stack  and  push  the  value  onto  it. 

lx  Push  the  value  in  register  X  onto  the  stack.  The  register  x  is  not  altered.  All  registers  start  with 

zero  value. 

Lx  Treat  register  x  as  a  stack,  and  pop  its  top  value  onto  the  main  stack, 

d  Duplicate  the  top  value  on  the  stack. 

p  Print  the  top  value  on  the  stack.  The  top  value  remains  unchanged. 

P  Interpret  the  top  of  the  stack  as  an  ASCII  string,  remove  and  print  it. 

f  Print  all  values  on  the  stack  and  in  registers. 

q  Exit  the  program.  If  executing  a  string,  pop  the  recursion  level  by  two. 

Q  Pop  the  top  value  on  the  stack,  and  pop  the  string  execution  level  by  that  value. 

X  Treat  the  top  element  of  the  stack  as  a  character  string  and  execute  it  as  a  string  of  dc  com¬ 

mands. 

X  Replace  the  number  on  the  top  of  the  stack  with  its  scale  factor. 

[ . . .  ]  Put  the  bracketed  ASCII  string  onto  the  top  of  the  stack. 

<x  >x  =x  Pop  and  compare  top  two  elements  of  the  stack.  Execute  register  x  if  they  obey  the  stated  rela¬ 
tion. 

V  Replace  the  top  element  on  the  stack  by  its  square  root.  Any  existing  fractional  part  of  the 

argument  is  taken  into  account,  but  otherwise  the  scale  factor  is  ignored. 

!  Interpret  the  rest  of  the  line  as  a  command. 

c  Clear  all  values  on  the  stack. 

i  Pop  the  top  value  on  the  stack  and  use  that  value  as  the  input  radix. 

I  Push  the  input  base  on  the  top  of  the  stack. 

0  Pop  the  top  value  on  the  stack  and  use  as  the  output  radix. 
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O  Push  the  output  base  on  the  top  of  the  stack. 

k  The  top  of  the  stack  is  popped,  and  that  value  is  used  as  a  non-negative  scale  factor:  the 

appropriate  number  of  places  are  printed  on  output,  and  maintained  during  multiplication,  divi¬ 
sion,  and  exponentiation.  The  interaction  of  scale  factor,  input  base,  and  output  base  will  be 
reasonable  if  all  are  changed  together. 

z  Push  the  stack  level  onto  the  stack. 

Z  Replace  the  number  on  the  top  of  the  stack  with  its  length. 

?  Take  a  line  of  input  from  the  input  source  (usually  the  terminal)  and  execute  it. 

; :  Used  by  be  for  array  operations. 

EXAMPLE 

Print  the  first  ten  values  of  n! 

[  lal  +  dsa  *  plalO  >  y  ]sy 

Osal 

lyx 


SEE  ALSO 

bed) 

DIAGNOSTICS 

X  is  unimplemented 
stack  empty 
Out  of  space 
Out  of  headers 
Out  of  pushdown 
Nesting  Depth 


Where  x  is  an  octal  number. 

For  not  enough  elements  on  the  stack  to  do  what  was  asked. 
When  the  free  list  is  exhausted  (too  many  digits). 

For  too  many  numbers  being  kept  around. 

For  too  many  items  on  the  stack. 

For  too  many  levels  of  nested  execution. 


BUGS 

Base  conversions  on  fractions  are  truncated  to  the  number  of  fractional  digits  of  the  input  value.  The 
values  are  not  rounded. 
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NAME 

dd  -  convert  and  copy  files  with  various  data  formats 
SYNOPSIS 

dd  [  option=value  ] . . . 


DESCRIPTION 

dd  copies  a  specified  input  file  to  a  specified  output  with  possible  conversions.  The  standard  input  and  out¬ 
put  are  used  by  default.  The  input  and  output  block  size  may  be  specified  to  take  advantage  of  raw  physi¬ 
cal  I/O. 


OPTIONS 

\f=name 

of=name 


Input  file  is  taken  from  name;  standard  input  is  default. 

Output  file  is  taken  from  name;  standard  output  is  default.  Note:  dd  creates  an  explicit 
output  file;  therefore  the  seek  option  is  usually  useless  with  explicit  output  except  in  spe¬ 
cial  cases  such  as  using  magnetic  tape  or  raw  disk  files. 

Input  block  size  n  bytes  (default  512). 

Output  block  size  n  bytes  (default  512). 

Set  both  input  and  output  block  size,  superseding  ibs  and  obs;  also,  if  no  conversion  is 
specified,  it  is  particularly  efficient  since  no  copy  need  be  done.  Block  sizes  for  the 
Sun386i  are  9k  for  3.5-inch  floppy  disks,  and  126b  (blocks)  for  quarter-inch  tapes. 

Conversion  buffer  size. 

Skip  n  input  records  before  starting  copy 

Copy  n  input  files  before  terminating  (makes  sense  only  when  input  is  a  magtape  or 
similar  device). 

Seek  n  records  from  beginning  of  output  file  before  copying.  This  option  generally  only 
works  with  magnetic  tapes  and  raw  disk  files  and  is  otherwise  usually  useless  if  the 
explicit  output  file  was  named  with  the  of  option. 

Copy  only  n  input  records, 

conv=ascii  Convert  EBCDIC  to  ASCII, 

ebcdic  Convert  ASCII  to  EBCDIC, 

ibm  Slightly  different  map  of  ASCII  to  EBCDIC, 

block  Convert  variable  length  records  to  fixed  length, 
unblock  Convert  fixed  length  records  to  variable  length, 

lease  Map  alphabetics  to  lower  case, 

ucase  Map  alphabetics  to  upper  case, 

swab  Swap  every  pair  of  bytes, 

noerror  Do  not  stop  processing  on  an  error, 
sync  Pad  every  input  record  to  ibs. 
arg,arg 

Several  comma-separated  conversions,  for  a  combination  of  effects.  For  instance, 
conv=sync, block  is  useful  for  reading  variable-length  output  from  a  pipe. 

Where  sizes  are  specified,  a  number  of  bytes  is  expected.  A  number  may  end  with  k  (kilobytes)  to  specify 
multiplication  by  1024,  b  (blocks  of  512  bytes)  to  specify  multiplication  by  512,  or  w  (words)  to  specify 
multiplication  by  4;  a  pair  of  numbers  may  be  separated  by  x  to  indicate  a  product. 


ibs=« 

obs=n 

hs=n 

cbs=/i 

skip=n 

files=n 

seek=n 

count=/i 


/■ 
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cbs  is  used  only  if  ascii,  unblock,  ebcdic,  ibm,  or  block  conversion  is  specified.  In  the  first  two  cases,  cbs 
characters  are  placed  into  the  conversion  buffer,  any  specified  character  mapping  is  done,  trailing  blanks 
trimmed  and  NEWLINE  added  before  sending  the  line  to  the  output.  In  the  latter  three  cases,  characters  are 
read  into  the  conversion  buffer,  and  blanks  added  to  make  up  an  output  record  of  size  cbs. 

After  completion,  dd  reports  the  number  of  whole  and  partial  input  and  output  blocks. 

EXAMPLES 

To  read  an  EBCDIC  tape  blocked  ten  80-byte  EBCDIC  card  images  per  record  into  the  ASCII  file  x: 

example%  dd  if = /dev/rmtO  of  =  x  ibs = 800  cbs  =  80  conv  =  ascii, lease 

Note:  the  use  of  raw  magtape:  dd  is  especially  suited  to  VO  on  the  raw  physical  devices  because  it  allows 
reading  and  writing  in  arbitrary  record  sizes. 

Sun386i  EXAMPLES 

The  following  write  the  fi\Q  filename  to  a  3.5-inch  floppy  and  read  from  the  floppy  into  a  hie  filename, 
respectively: 

example  %  dd  it=filename  of=/dev/rfdOc  bs=9k 
example  %  dd  if=/dev/rfdOc  of=yi/en£2me  bs=9k 

Sun386i  files  names  are  shown  in  fdformat(l). 

SEE  ALSO 

cp(l),  fdformat(l),  tr(lV) 

DIAGNOSTICS 

f+p  records  in(out): 

Numbers  of  full  and  partial  records  read(written). 

BUGS 

The  ASCn/EBCDIC  conversion  tables  are  taken  from  the  256  character  standard  in  the  CACM  Nov,  1968. 
The  ibm  conversion,  while  less  blessed  as  a  standard,  corresponds  better  to  certain  IBM  print  train  conven¬ 
tions.  There  is  no  universal  solution. 

The  block  and  unblock  options  cannot  be  combined  with  the  ascii,  ebcdic  or  ibm.  Invalid  combinations 
silently  ignore  all  but  the  last  mutually-exclusive  keyword. 
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NAME 

defaultsedit,  defaQlts_from_input,  defaults_to_mdentpro,  defaults_to_mailrc,  indentpro_to_defaults, 
input_from_defaults,  lockscreen_defauIt,  mailrc_to_defaults,  scrolldefaults,  stty_from_defaults  ~  create  or 
edit  default  settings  for  Sun  View  utilities 

SYNOPSIS 

defaultsedit  [  generic-tool-arguments  ] 

defaults_from_input 

defaults_to_indentpro 

defaults_to_inailrc 

indentpro_to_defaults 

input^fromdefaults 

lockscreendefault 

mailrctodefaults 

scrolldefaults 


sttyfromdefaults 

AVAILABILITY 

These  commands  are  available  with  the  SunView  User’s  Guide  software  installation  option.  Refer  to  Ins¬ 
talling  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

defaultsedit  is  a  SunView  application  that  provides  a  convenient  means  for  inspecting  and  setting  default 
parameters.  It  can  be  viewed  as  an  alternative  to  the  traditional  UNIX  operating  system  .  *rc  files  that  con¬ 
tain  initialization  options  for  various  commands.  Currently,  you  can  use  defaultsedit  to  manipulate  options 
to  the  programs  indent(l),  mail(l)  and  maiitooKl),  stty(lV),  and  defaultsedit,  as  well  as  the  menu, 
scrollbar,  text  subwindow  and  tty  subwindow  packages,  and  the  SunView  environment  itself. 

The  remaining  commands  are  used  by  defaultsedit  to  perform  conversions  and  other  functions;  they  can 
also  be  invoked  directly  from  the  shell: 


defaults_from_input  update  window-system  I/O  defaults  from  current  system  values 
defaults_to_indentpro  update  indent(l)  defaults  in  the  database  from  the  .indentpro  file 
defaults_to_mailrc  update  the  .mailrc  file  from  the  defaults  database 
indentpro_to_defaults  update  indent  defaults  from  the  .indent.pro  file 
input__from_defaults  update  current  system  values  for  window-system  I/O  from  defaults  data¬ 
base 


lockscreendefault 

mailrctodefaults 

scrolldefaults 

stty__from_defaults 


apply  current  default  for  lockscreen(l)  display  program 

update  mail(l)  and/or  mailtool(l)  defaults  from  the  .mailrc  file 

a  SunView  application  that  lets  you  try  out  different  settings  from  the 

Scrollbar  category  interactively 

set  terminal  (TTY)  options  from  defaults  database 


Any  program  or  package  that  a  user  can  customize  by  setting  or  changing  a  parameter  could  be  written  so 
as  to  get  its  initialization  options  from  the  defaults  database.  For  further  information,  see  SunView  System 
Programmer’s  Guide. 
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OPTIONS 

defaultsedit  accepts  all  of  the  generic  tool  arguments  discussed  in  sunview(l). 

USAGE 

This  only  applies  to  defaultsedit. 


Subwindows 

defaultsedit  consists  of  four  subwindows.  From  top  to  bottom  they  are: 

control  Contains  the  name  of  the  category  currently  displayed,  and  buttons  labeled  SAVE,  QUIT, 

RESET,  and  EDIT  ITEM.  To  change  the  category,  click  the  LEFT  mouse  button  on  the 
word  CATEGORY,  or  use  the  menu  that  pops  up  when  you  click  the  RIGHT  mouse  but¬ 
ton. 


message 

parameters 

edit 

Control  Panel 
SAVE 

QUIT 

RESET 

EDIT  ITEM 


A  small  text  subwindow  where  messages  from  defaultsedit  are  displayed. 

Shows  all  current  default  parameter  names  with  corresponding  values.  Clicking  the 
LEFT  mouse  button  over  a  parameter  displays  a  help  string  in  the  message  subwindow. 

A  small  text  subwindow  which  enables  text  editing  of  parameter  values.  This  is  useful 
for  very  long  text  values,  such  as  a  long  mailing  list. 

Save  the  current  values  that  differ  from  the  standard  defaults  in  your  private  database  — 
that  is,  the  .defaults  file  in  your  home  directory. 

Exit  without  saving  any  changes. 

Reset  the  default  parameters  of  the  current  category  to  the  values  in  your  private  data¬ 
base.  This  is  useful  if  you  change  some  values,  then  change  your  mind  and  want  to 
restore  the  original  values. 

Clicking  the  RIGHT  mouse  button  over  the  EDIT  ITEM  button  brings  up  a  menu  with 
three  choices:  COPY  ITEM,  DELETE  ITEM  and  EDIT  LABEL.  Only  text  or  numeric  items 
can  be  edited.  Note:  edits  made  using  this  menu  will  appear  only  in  your  private 
defaults  database,  not  in  the  master  database.  The  three  editing  operations  are  described 
below. 


COPY  ITEM  Choosing  COPY  ITEM  will  duplicate  the  current  item.  You  can  then  edit  both  the  label 
and  the  value  of  the  newly  created  item.  Only  items  with  text  or  numeric  values  can  be 
copied  in  this  way.  COPY  ITEM  is  useful  when  you  want  to  change  the  number  of 
instances  of  a  certain  type  of  item  —  for  example,  to  insert  a  new  mail  alias  into  your 
defaults  database. 


DELETE  ITEM  Choosing  DELETE  ITEM  will  delete  the  current  item  from  your  private  database.  It  can¬ 

not  be  permanently  deleted  if  the  corresponding  node  is  present  in  the  master  database. 
However,  you  can  make  it  behave  like  an  undefined  node  by  giving  it  the  special  value 
255Undefined255 . 

EDIT  LABEL  Choosing  EDIT  LABEL  allows  you  to  edit  the  label  of  the  current  item.  When  you  choose 
EDIT  LABEL,  the  label  of  the  current  item  changes  from  bold  to  normal  face.  Then  you 
can  select  the  label  and  edit  it  as  a  normal  panel  text  item. 

Note:  SunView  starts  up  faster  when  you  set  the  Private_only  parameter  in  the  Defaults  category  to 

TRUE,  in  which  case  only  your  private  .defaults  file  is  read. 


ENVIRONMENT 

DEFAULTS_FILE  The  value  of  this  environment  variable  indicates  the  file  from  which  private  Sun- 
View  defaults  are  read.  When  it  is  undefined,  defaults  are  read  from  the  .defaults 
file  in  your  home  directory. 
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FILES 

/usr/lib/defaults/*.d  System-wide  parameters  and  their  standard  settings.  Each  file  is  a  category  in 
defaultsedit. 

^.defaults 
SEE  ALSO 

indent(l),  lockscreen(l),  mail(l),  mailtool(l),  stty(lV),  sunview(l) 

SunView  User's  Guide 

SunView  System  Programmer's  Guide 

BUGS 

Editing  of  choice  items  or  categories  is  not  supported  by  defaultsedit.  Neither  is  editing  of  the  master 
defaults  database  —  to  add  a  new  program  to  the  master  defaults  database,  you  have  to  edit  a  master 
defaults  textfile. 

defaultsedit  reorders  mail  aliases  that  appear  in  the  .mailrc  file.  This  can  adversely  affect  recursive  mail 
aliases.  To  avoid  this,  use  the  source  command  for  mail(l)  to  include  a  file  containing  such  aliases. 
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NAME 

deroff-  remove  nroff»  tnoff,  tbl  and  eqn  constructs 
SYNOPSIS 

deroff  [  -w  ]  filename  , . . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

deroff  reads  each  file  in  sequence  and  removes  all  nroff  and  troff  command  lines,  backslash  constructions, 
macro  definitions,  eqn  constructs  (between  .EQ  and  .EN  lines  or  between  delimiters),  and  table  descriptions 
and  writes  the  remainder  on  the  standard  output,  deroff  follows  chains  of  included  files  (,so  and  .nx  com¬ 
mands);  if  a  file  has  already  been  included,  a  .so  is  ignored  and  a  ,nx  terminates  execution.  If  no  input  file 
is  given,  deroff  reads  from  the  standard  input  file. 

OPTIONS 

-w  Generate  a  word  list,  one  word  per  line.  A  ‘word’  is  a  string  of  letters,  digits,  and  apostrophes, 
beginning  with  a  letter;  apostrophes  are  removed.  All  other  characters  are  ignored. 

SEE  ALSO 

eqii(l),  nroff(l),  tbl(l),  troff(l) 

BUGS 

deroff  is  not  a  complete  troff  interpreter,  so  it  can  be  confused  by  subtle  constructs.  Most  errors  result  in 
too  much  rather  than  too  little  output. 

deroff  does  not  work  well  with  files  that  use  .so  to  source  in  the  standard  macro  package  files. 
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NAME 

des  -  encrypt  or  decrypt  data  using  Data  Encryption  Standard 
SYNOPSIS 

des  -e  I  -d  [  -bfs  ][-kkey][  input-file  [  output-file  ]  ] 

DESCRIPTION 

des  encrypts  and  decrypts  data  using  the  NBS  Data  Encryption  Standard  algorithm.  One  of -e  (for  encrypt) 
or  -d  (for  decrypt)  must  be  specified. 

The  des  command  is  provided  to  promote  secure  exchange  of  data  in  a  standard  fashion. 

Two  standard  encryption  modes  are  supported  by  the  des  program.  Cipher  Block  Chaining  (CBC  —  the 
default)  and  Electronic  Code  Book  (ECB  —  specified  with  -b).  CBC  mode  treats  an  entire  file  as  a  unit  of 
encryption,  that  is,  if  insertions  or  deletions  are  made  to  the  encrypted  file  then  decryption  will  not  succeed. 
CBC  mode  also  ensures  that  regularities  in  clear  data  do  not  appear  in  the  encrypted  data.  ECB  mode  treats 
each  8  bytes  as  units  of  encryptions,  so  if  parts  of  the  encrypted  file  are  modified  then  other  parts  may  still 
be  decrypted.  Identical  values  of  clear  text  encrypt  to  identical  values  of  cipher  text. 

The  key  used  for  the  DES  algorithm  is  obtained  by  prompting  the  user  unless  the  ‘-k  key*  option  is  given. 
If  the  key  is  an  argument  to  the  des  command,  it  is  potentially  visible  to  users  executing  ps(l)  or  a  deriva¬ 
tive.  To  minimize  this  possibility,  des  takes  care  to  destroy  the  key  argument  immediately  upon  entry. 

The  des  command  attempts  to  use  DES  hardware  for  its  job,  but  will  use  a  software  implementation  of  the 
DES  algorithm  if  the  hardware  is  unavailable.  Normally,  a  warning  message  is  printed  if  the  DES  hardware 
is  unavailable  since  the  software  is  only  about  l/50th  as  fast.  However,  the  -f  option  will  suppress  the 
warning.  The  ~s  option  may  be  used  to  force  use  of  software  instead  of  hardware  DES, 

The  des  command  reads  fi'om  standard  input  unless  input-file  is  specified  and  writes  to  standard  output 
unless  output-file  is  given. 

The  following  sections  give  information  required  to  implement  compatible  facilities  in  other  environments. 

Since  the  CBC  and  ECB  modes  of  DES  require  units  of  8  bytes  to  be  encrypted,  files  being  encrypted  by  the 
des  command  have  1  to  8  bytes  appended  to  them  to  cause  them  to  be  a  multiple  of  8  bytes.  The  last  byte, 
when  decrypted,  gives  the  number  of  bytes  (0  to  7)  which  are  to  be  saved  of  the  last  8  bytes.  The  other 
bytes  of  those  appended  to  the  input  are  randomized  before  encryption.  If,  when  decrypting,  the  last  byte  is 
not  in  the  range  of  0  to  7  then  either  the  encrypted  file  has  been  corrupted  or  an  incorrect  key  was  provided 
for  decryption  and  an  error  message  is  printed. 

The  DES  algorithm  requires  an  8  byte  key  whose  low  order  bits  are  assumed  to  be  odd-parity  bits.  The 
ASCn  key  supplied  by  the  user  is  zero  padded  to  8  bytes  and  the  high  order  bits  are  set  to  be  odd-parity 
bits.  The  DES  algorithm  then  ignores  the  low  bit  of  each  ASCII  character,  but  that  bit’s  information  has 
been  preserved  in  the  high  bit  due  to  the  parity. 

The  CBC  mode  of  operation  always  uses  an  initial  value  of  all  zeros  for  the  initialization  vector,  so  the  first 
8  bytes  of  a  file  are  encrypted  the  same  whether  in  CBC  or  ECB  mode. 

OPTIONS 

-b  Select  ECB  (eight  bytes  at  a  time)  encryption  mode. 

-d  Decrypt  data. 

-e  Encrypt  data. 

“f  Suppress  warning  message  when  software  implementation  is  used. 

-s  Select  software  implementation  for  the  encryption  algorithm. 

-k  key  Use  the  encryption  key  specified. 

FILES 

/dev/des? 
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SEE  ALSO 

ps(l) 


BUGS 

It  would  be  better  to  use  a  real  56-bit  key  rather  than  an  ASCn-based  56-bit  pattern.  Knowing  that  the  key 
was  derived  from  ASCII  radically  reduces  the  time  necessary  for  a  brute-force  cryptographic  attack. 

RESTRICTIONS 

Software  encryption  is  disabled  for  programs  shipped  outside  of  the  U.S.  The  program  will  still  be  able  to 
encrypt  files  if  one  can  obtain  an  encryption  chip,  legally  or  otherwise. 
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NAME 

df  ~  report  free  disk  space  on  file  systems 
SYNOPSIS 

df  [  -a  ]  [  -i  ]  [  -t  type  ]  [filesystem . . .  ]  [filename. . .  ] 

SYSTEM  V  SYNOPSIS 

/usr/5bin/df  [  -t }  [filesystem. . .  ]  [filename. . .  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

df  displays  the  amount  of  disk  space  occupied  by  currently  mounted  file  systems,  the  amount  of  used  and 
available  space,  and  how  much  of  the  file  system’s  total  capacity  has  been  used.  Used  without  arguments, 
df  reports  on  all  mounted  file  systems,  producing  something  like: 

example  %  df 

Filesystem  kbytes  used  avail  capacity  Mounted  on 

/dev/ipOa  7445  4714  1986  70%  / 

/dev/ipOg  42277  35291  2758  93%  /usr 

Note:  used+avail  is  less  than  the  amount  of  space  in  the  file  system  (kbytes);  this  is  because  the  system 
reserves  a  fraction  of  the  space  in  the  file  system  to  allow  its  file  system  allocation  routines  to  work  well. 
The  amount  reserved  is  typically  about  10%;  this  may  be  adjusted  using  tunefs(8).  When  all  the  space  on  a 
file  system  except  for  this  reserve  is  in  use,  only  the  super-user  can  allocate  new  files  and  data  blocks  to 
existing  files.  When  a  file  system  is  overallocated  in  this  way,  df  may  report  that  the  file  system  is  more 
than  100%  utilized. 

If  arguments  to  df  are  disk  partitions  (for  example,  /dev/ipOas  or  path  names,  df  produces  a  report  on  the 
file  system  containing  the  named  file.  Thus  ‘df »’  shows  the  amount  of  space  on  the  file  system  containing 
the  current  directory. 

SYSTEM  V  DESCRIPTION 

The  System  V  version  of  df  works  in  the  same  manner  as  above  but  prints  only  the  amount  of  available 
space  (in  5 12  byte  units)  and  the  number  of  free  inodes. 

OPTIONS 

-a  Report  on  all  filesystems  including  the  uninteresting  ones  which  have  zero  total  blocks,  (that  is, 
automounter) 

-i  Report  the  number  of  used  and  free  inodes.  Print  if  no  information  is  available. 

-t  type  Report  on  filesystems  of  a  given  type  (for  example,  nfs  or  4.2). 

SYSTEM  V  OPTIONS 

-t  Report  the  total  allocated  space  figures. 

FILES 

/etc/mtab  List  of  filesystems  currently  mounted. 

SEE  ALSO 

du(lV),  mtab(5),  quot(8),  tunefs(8) 


152 


Last  change:  16  September  1989 


Sun  Release  4.1 


DIFF(l) 


USER  COMMANDS 


DIFF(l) 


NAME 

diff-  display  line-by-line  differences  between  pairs  of  text  files 

SYNOPSIS 

dilT  [  -bitw  ]  [  — c  [  #  ]  1  -e  I  “f  I  -n  I  -h  ]  filenamel  filename! 
diff  [  -bitw  ]  [  -Dstring  ]  filenamel  filename! 

diff  [  -bitw  ]  [  -c  [  #  ]  1  -e  I  -f  i  -n  I  -h  ]  [  -I  ]  [  -r  ]  [  -s  ]  [  -Sname  ]  directory  1  directory! 

DESCRIPTION 

diff  is  a  differential  file  comparator.  When  ran  on  regular  files,  and  when  comparing  text  files  that  differ 
during  directory  comparison  (see  the  notes  below  on  comparing  directories),  diff  tells  what  lines  must  be 
changed  in  the  files  to  bring  them  into  agreement.  Except  in  rare  circumstances,  diff  finds  a  smallest 
sufficient  set  of  differences.  If  neither  filenamel  nor  filename!  is  a  directory,  either  may  be  given  as  in 
which  case  the  standard  input  is  used.  If  filenamel  is  a  directory,  a  file  in  that  directory  whose  filename  is 
the  same  as  the  filename  of  filename!  is  used  (and  vice  versa). 

There  are  several  options  for  output  format;  the  default  output  format  contains  lines  of  these  forms; 

nl  sin3,n4 
nl,n!  dn3 
nl,n!  c  n3,n4 

These  lines  resemble  ed(l)  commands  to  convert  filenamel  into  filename!.  The  numbers  after  the  letters 
pertain  tD  filename!.  In  fact,  by  exchanging  a  for  d  and  reading  backward  one  may  ascertain  equally  how 
to  convert  filename!  into  filenamel .  As  in  ed(l),  identical  pairs,  where  nl  =  n!  or  n3  =  n4,mQ  abbrevi¬ 
ated  as  a  single  number. 

Following  each  of  these  lines  come  all  the  lines  that  are  affected  in  the  first  file  flagged  by  then  all  the 
lines  that  are  affected  in  the  second  file  flagged  by 

If  both  arguments  are  directories,  diff  sorts  the  contents  of  the  directories  by  name,  and  then  runs  the  regu¬ 
lar  file  diff  program  as  described  above  on  text  files  which  are  different.  Binary  files  which  differ,  com¬ 
mon  subdirectories,  and  files  which  appear  in  only  one  directory  are  listed. 

OPTIONS 

-b  Ignore  trailing  blanks  (SPACE  and  TAB  characters)  and  treat  all  other  strings  of  blanks  as 
equivalent. 

-i  Ignore  the  case  of  letters;  for  example,  ‘A’  will  compare  equal  to  ‘a’. 

-t  Expand  TAB  characters  in  output  lines.  Normal  or  ~c  output  adds  character(s)  to  the  front  of  each 
line  which  may  alter  the  indentation  of  the  original  source  lines  and  make  the  output  listing 
difficult  to  interpret.  This  option  will  preserve  the  original  source’s  indentation. 

-w  Ignore  all  blanks  (SPACE  and  TAB  characters);  for  example,  ‘if  ( a  =  =  b )’  will  compare  equal  to 
‘if(a==b)’. 

The  following  four  options  are  mutually  exclusive: 

“C[#]  Produce  a  listing  of  differences  with  lines  of  context.  The  default  is  to  present  3  lines  of  context 
and  may  be  changed,  (to  10,  for  example),  by  -clO.  With  -c  the  output  format  is  modified 
slightly:  output  begins  with  identification  of  the  files  involved  and  their  creation  dates,  then  each 
change  is  separated  by  a  line  with  a  dozen  *  s.  The  lines  removed  from  filenamel  are  marked  with 
those  added  to  filename!  are  marked  *+  ’.  Lines  which  are  changed  from  one  file  to  the  other 
are  marked  in  both  files  with  ‘!  *. 

Changes  which  lie  within  <context>  lines  of  each  other  are  grouped  together  on  output.  This  is  a 
change  from  the  previous  ‘diff-c’  but  the  resulting  output  is  usually  much  easier  to  interpret. 

-e  Produce  a  script  of  a,  c,  and  d  commands  for  the  editor  ed,  which  will  recreate  filename!  from 
filenamel . 
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In  connection  with  -e,  the  following  shell  program  may  help  maintain  multiple  versions  of  a  file. 
Only  an  ancestral  file  ($1)  and  a  chain  of  version-to-version  ed  scripts  ($2, $3,...)  made  by  diff 
need  be  on  hand.  A  ‘latest  version’  appears  on  the  standard  output 

(shift;  cat  $*;  echo  'l,$p')  |  ed  ~  $1 

Extra  commands  are  added  to  the  output  when  comparing  directories  with  -e»  so  that  the  result  is 
a  sh  script  for  converting  text  files  which  are  common  to  the  two  directories  firom  their  state  in 
directory  1  to  their  state  in  directory! . 

-f  Produce  a  script  similar  to  that  of  -e,  not  useful  with  ed,  which  is  in  the  opposite  order. 

-n  Produce  a  script  similar  to  that  of-e,  but  in  the  opposite  order  and  with  a  count  of  changed  lines 

on  each  insert  or  delete  command. 

-h  Do  a  fast,  half-hearted  job.  It  works  only  when  changed  stretches  are  short  and  well  separated, 
but  does  work  on  files  of  unlimited  length. 

Options  for  the  second  form  of  diff  are  as  follows: 

-Dstring 

Create  a  merged  version  of  filename!  and  filename!  on  the  standard  output,  with  C  preprocessor 
controls  included  so  that  a  compilation  of  the  result  without  defining  string  is  equivalent  to  com- 
pilingfilenamel ,  while  defining  string  will  yield  filename!. 

Options  when  comparing  directories  are; 

-1  Long  output  format;  each  text  file  diff  is  piped  through  pr(lV)  to  paginate  it,  other  differences  are 
remembered  and  summarized  after  all  text  file  differences  are  reported. 

-r  Apply  diff  recursively  to  common  subdirectories  encountered. 

-s  Report  files  which  are  the  same,  which  are  otherwise  not  mentioned. 

-Sname 

Start  a  directory  diff  in  the  middle,  beginning  with  file  name. 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_^defauIt  control  the  character  classification 
throughout  diff.  On  en&y  to  diff,  these  environment  variables  are  checked  in  the  following  order: 
LC^CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC  CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSDC.l  “C”  locale. 

FILES 

/tmp/d????? 

/usr/lib/diffh  for  -h 

SEE  ALSO 

cc(lV),  cmp(l),  comm(l),  cpp(l),  diff3(lV),  ed(l),  pr(lV),  localc(5),  iso_8859_l(7) 

DIAGNOSTICS 

Exit  status  is  0  for  no  differences,  1  for  some  differences,  2  for  trouble. 

Missing  newline  at  end  of  fileX 

Indicates  that  the  last  line  of  file  X  did  not  have  a  NEWLINE.  If  the  lines  are  different,  they  will  be 
flagged  and  output,  although  the  output  will  seem  to  indicate  they  are  the  same. 
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BUGS 

Editing  scripts  produced  under  the  -e  or  -f  option  are  naive  about  creating  lines  consisting  of  a  single 

When  comparing  directories  with  the  ~b,  -w,  or  -i  options  specified,  diff  first  compares  the  files  (as  in 
cmp(l),  and  then  runs  the  regular  diff  algorithm  if  they  are  not  equal.  This  may  cause  a  small  amount  of 
spmous  output  if  the  files  then  turn  out  to  be  identical  because  the  only  differences  are  insignificant  blank 
string  or  case  differences. 

The  ~D  option  ignores  existing  preprocessor  controls  in  the  source  files,  and  can  generate  #ifdefs’s  with 
overlapping  scope.  The  output  should  be  checked  by  hand,  or  run  through  ‘cc  -E*  (see  cc(lV))  and  then 
diffed  with  the  original  source  files.  Discrepancies  revealed  should  be  corrected  before  compilation. 
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NAME 

diff3  -  display  line-by-line  differences  between  3  files 
SYNOPSIS 

difl3  [-exEX3  ]filenamel  filename!  filenames 
SYSTEM  V  SYNOPSIS 

/usr/5bin/diff3  [  -ex3  ]  filename!  filename!  filenames 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
io  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

difl3  compares  three  versions  of  a  file,  and  publishes  disagreeing  ranges  of  text  flagged  with  these  codes: 
=====  All  three  files  differ 

====1  filename!  is  different 

====2  filename!  is  different 

====3  filenames  is  different 

The  types  of  differences  between  a  given  range  within  the  given  files  are  indicated  in  one  of  these  ways: 

/;  n!  a  Text  is  to  be  appended  after  line  number  n!  in  file/,  where/=  1 , 2,  or  3. 

/:  n!^n2c  Text  is  to  be  changed  in  the  range  line  n!  to  line  n2.  If  n!  =n2,  the  range  may  be 

abbreviated  to  n! . 

The  original  contents  of  the  range  follows  immediately  after  a  c  indication.  When  the  contents  of  two  files 
are  identical,  the  contents  of  the  lower-numbered  file  is  suppressed. 

OPTIONS 

The  options  to  diff3  instruct  it  to  produce  a  script  for  the  editor  ed,  rather  than  a  list  of  differences.  This 
script  will  incorporate  some  or  all  of  the  differences  between  filename!  and  filenames  into  filename! .  This 
script  will  not  include  a  w  or  q  command  at  the  end,  so  that  it  will  not  write  out  the  changed  file. 

-e  Produce  a  script  that  will  incorporate  all  changes  between  filename!  and  filenames,  that  is,  the 
changes  that  normally  would  be  flagged  ‘====’  and  ‘====3’. 

“X  Produce  a  script  that  will  incorporate  only  changes  flagged  *===;=’. 

-3  Produce  a  script  that  will  incorporate  only  changes  flagged  ‘====3’. 

-E  Produce  a  script  that  will  incorporate  all  changes  between  filename!  and  filenames ,  but  treat  over¬ 

lapping  changes  (that  is,  changes  that  would  be  flagged  with  =====  in  the  normal  listing)  dif¬ 
ferently.  The  overlapping  lines  from  both  files  will  be  inserted  by  the  edit  script,  bracketed  by 
«««  and  »»» lines. 

-X  Produce  a  script  that  will  incorporate  only  changes  flagged  ====,  but  treat  these  changes  in  the 
manner  of  the  -E  option. 
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For  example,  suppose  lines  7-8  are  changed  in  both  filenamel  and  filename2 .  Applying  the  edit 
script  generated  by  the  command 

difD  -E  filenamel  filename2  filenames 

to  filenamel  results  in  the  following  file. 

lines  1-6 
of  filenamel 
«««<  filenamel 
lines  7-8 
of  filenamel 


lines  7-8 

of  filenames 
»»»>  filenames 
rest  of  filenamel 

SYSTEM  V  OPTIONS 

The  System  V  version  of  diffiS  does  not  support  the  -E  and  ~X  options.  The  script  produced  by  the  -e,  -x, 
and  -3  options  does  include  a  w  and  q  command  at  the  end,  so  that  it  will  write  out  the  changed  file. 

EXAMPLES 

The  following  command  will  incorporate  all  the  changes  between  filename2  and  filenames  into  filenamel , 
and  print  the  resulting  file  to  the  standard  output.  If  the  System  V  version  of  diff3,  is  filenamel  will 
be  replaced  with  the  resulting  file. 

(difl3  filenamel  filename2  filenames ;  echo  '1,  $p' )  |  ed  —  filenamel 

FILES 

/tmp/d3????? 

/usr/lib/difR 

/usr/51ib/difr3prog 

SEE  ALSO 

diff(l),  ed(l) 

BUGS 

Text  lines  that  consist  of  a  single  will  defeat  a  -e  option. 
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NAME 

diffmk  ~  mark  differences  between  versions  of  a  troff  input  file 
SYNOPSIS 

difTmk  oldjile  newfile  markedfile 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

diffmk  compares  two  versions  of  a  file  and  creates  a  third  version  that  includes  “change  mark”  (.me)  com¬ 
mands  for  nroff(l)  and  troff(l).  oldjile  and  newjile  are  the  old  and  new  versions  of  the  file,  diffmk  gen¬ 
erates  markedfile,  which,  contains  the  text  from  newjile  with  troff(l)  “change  mark”  requests  (.me) 
inserted  where  newjile  differs  from  oldjile.  When  markedfile  is  formatted,  changed  or  inserted  text  is 
shown  by  |  at  the  right  margin  of  each  line.  The  position  of  deleted  text  is  shown  by  a  single  *. 

diffmk  can  also  be  used  in  conjunction  with  the  proper  troff  requests  to  produce  program  listings  with 
marked  changes.  In  the  following  command  line: 

diffmk  old.c  new.c  markedx  ;  nroff  reqs  marked.c  |  pr 

the  file  reqs  contains  the  following  troff  requests: 

.pll 
.11  77 
.nf 
.eo 
.nh 

which  eliminate  page  breaks,  adjust  the  line  length,  set  no-fill  mode,  ignore  escape  characters,  and  turn  off 
hyphenation,  respectively. 

If  the  characters  |  and  *  are  inappropriate,  you  might  run  markedfile  through  sed(IV)  to  globally  change 
them. 

SEE  ALSO 

diff(l),  nroff(l),  sed(lV),  troff(l) 

BUGS 

Aesthetic  considerations  may  dictate  manual  adjustment  of  some  ouq)ut.  File  differences  involving  only 
formatting  requests  may  produce  undesirable  output,  that  is,  replacing  .sp  by  .sp  2  will  produce  a  “change 
mark”  on  the  preceding  or  following  line  of  output. 
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NAME 

dircmp  -  compare  directories 
SYNOPSIS 

/usr/Sbin/dircmp  [  -d  ]  [  -s  ]  [  -w/i  ]  dirl  dir2 
AVAILABILITY 

piis  command  is  available  with  the  System  V  software  installation  option.  See  Installing  SunOS  4.1  for 
information  on  how  to  install  this  command. 

DESCRIPTION 

dircmp  examines  dirl  and  dirl  and  generates  various  tabulated  information  about  the  contents  of  the 
directories.  Listings  of  files  that  are  unique  to  each  directory  are  generated  for  all  the  options.  If  no  option 
is  entered,  a  list  is  output  indicating  whether  the  filenames  common  to  both  directories  have  the  same  con¬ 
tents. 

OPTIONS 

-d  Compare  the  contents  of  files  with  the  same  name  in  both  directories  and  output  a  list  telling  what 
must  be  changed  in  the  two  files  to  bring  them  into  agreement.  The  list  format  is  described  in 
diff(l). 

-s  Suppress  messages  about  identical  files. 

-wn  Change  the  width  of  the  output  line  to  n  characters.  The  default  width  is  72. 

SEE  ALSO 

cmp(l),diff(l) 

Installing  SunOS  4.1 
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NAME 

dis  -  object  code  disassembler  for  COFF 
SYNOPSIS 

dis[-o][-V][-L][--d  sec  ]  [  -da  sec  ]  [  -F  function  ]  [  -t  sec  ]  [  -1  string  ]  coff-jile  . . . 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

The  dis  command  produces  an  assembly-language  listing  of  coff-Jile,  which  may  be  any  object  file  in  COFF 
format,  or  an  archive  of  COFF  object  files. 

The  listing  includes  assembly  statements  and  an  octal  or  hexadecimal  representation  of  the  binary  that  pro¬ 
duced  those  statements. 

OPTIONS 

-o  Print  numbers  in  octal.  The  default  is  hexadecimal. 

-V  Print,  on  standard  error,  the  version  number  of  the  disassembler  being  executed. 

-L  Lookup  source  labels  in  the  symbol  table  for  subsequent  printing.  This  option  works  only  if  the 
file  was  compiled  with  additional  debugging  information  (e.g.,  the  -g  option  of  cc(lV)). 

-d  sec  Disassemble  the  named  section  as  data,  printing  the  offset  of  the  data  from  the  beginning  of  the 
section. 

-da  sec  Disassemble  the  named  section  as  data,  printing  the  actual  address  of  the  data. 

-F  function 

Disassemble  only  the  named  function  in  each  object  file  specified  on  the  command  line.  The  -F 
option  may  be  specified  multiple  times  on  the  command  line. 

-t  sec  Disassemble  the  named  section  as  text 

-I  string 

Disassemble  the  library  file  specified  by  string.  For  example,  dis  -1  x  -I  z  disassembles  Ubx.a 
and  Iibz.a.  All  libraries  are  assumed  to  be  in  /usr/lib. 

If  the  -d,  -da  or  ~t  options  are  specified,  only  those  named  sections  from  each  user-supplied  file  name  will 
be  disassembled.  Otherwise,  all  sections  containing  text  will  be  disassembled. 

On  output,  a  number  enclosed  in  brackets  at  the  beginning  of  a  line,  such  as  [5],  represents  that  the  break- 
pointable  line  number  starts  with  the  following  instruction.  These  line  numbers  will  be  printed  only  if  the 
file  was  compiled  with  additional  debugging  information  (e.g.,  the  -g  option  of  cc(lV)).  An  expression 
such  as  <40>  in  the  operand  field  or  in  the  symbolic  disassembly,  following  a  relative  displacement  for 
control  transfer  instructions,  is  the  computed  address  within  the  section  to  which  control  will  be 
transferred.  A  function  name  will  appear  in  the  first  column,  followed  by  ( ). 

FILES 

/usr/lib 

SEE  ALSO 

cc(lV)  cofT(5) 

NOTES 

Because  the  assembler  does  not  generate  or  support  8-bit  symbol  names,  it  is  inappropriate  to  make  dis  8- 
bit  clean.  Seeas(l). 
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NAME 

domainname  -  set  or  display  name  of  the  current  NIS  domain 
SYNOPSIS 

domainname  [  name-of-domain  ] 

DESCRIPTION 

Without  an  argument,  domainname  displays  the  name  of  the  current  domain,  which  typically  encompasses 
a  group  of  hosts  under  the  same  administration.  As  such,  the  name  of  a  Network  Information  Service  (NIS) 
domain  is  normally  also  a  valid  Internet  domain  name,  and  can  be  used  in  conjunction  with  the  send- 
mail(8)  and  the  name  server  named(8C). 

Only  tile  super-user  can  set  the  name  of  the  domain,  by  giving  domainname  an  argument;  this  can  be  done 
only  in  the  startup  script  /etc/rc.local. 

SEE  ALSO 

named(8C),  sendmail(8),  ypinit(8) 

NOTES 

The  Network  Information  Service  (MS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed. 
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NAME 

dos  -  SunView  window  for  IBM  PC/AT  applications 
SYNOPSIS 

dos  [  -b  ]  [  -p  config  ]  [  -q  ]  [  -s  ]  [  -update  time  ]  [  -w  ]  [  -c  command  ] 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4,0 jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

A  window  created  by  dos  looks  and  acts  like  the  screen  of  an  IBM  PC/AT  or  compatible  computer  running 
MS-DOS  3.3,  except  that  it  has  expanded  features.  It  allows  sharing  of  files  with  the  SunOS  operating  sys¬ 
tem,  copying  and  pasting  data  between  windows,  and  piping  and  redirection.  You  may  run  any  reasonable 
number  of  DOS  windows  simultaneously. 

Shrinking  or  expanding  the  window  will  not  change  the  contents  to  accommodate  the  new  size. 

USAGE 

Menu 

The  menu  available  in  the  window  by  pressing  the  right  mouse  button  allows  various  controls  over  the 
work  in  the  window.  Edit  allows  you  to  copy  and  paste  between  windows.  The  Show  Screen  menu  item 
selects  the  type  of  screen  display — either  Hercules,  CGA,  or  Monochrome.  Use  the  DOS  MODE  command 
to  set  the  corresponding  DOS  display  mode.  See  the  Sun386i  User's  Guide  or  on-line  help  for  more  infor¬ 
mation.  The  Mouse  menu  item  allows  you  to  control  whether  the  mouse  operates  like  a  Microsoft  or  com¬ 
patible  mouse  or  in  normal  SunView  fashion  (see  Sun386i  Advanced  Skills  for  instructions  on  enabling 
Microsoft  mouse  driver  software).  The  Send  to  printer  menu  item  allows  you  to  send  queued  jobs  to  the 
print  spooler.  Sound  controls  the  volume  of  sounds  from  the  DOS  window.  Device  allows  you  to  select 
which  disks  and  other  devices  will  be  used  and  which  are  to  be  considered  write  only.  The  Reboot  DOS 
Window  item  is  equivalent  to  restarting  the  window.  This  can  also  be  accomplished  by  pressing  the  CON¬ 
TROL,  ALT,  and  DELETE  keys  simultaneously. 

Printer  Assignments 

DOS  uses  three  printer  designations:  LPTl,  LPT2,  and  LPT3.  The  default  settings  are:  files  sent  to  LPTl  go 
to  the  default  system  printer.  Files  sent  to  LPTl  are  appended  to  the  file  lpt-2  in  your  home  directory. 
Epson-compatible  print  jobs  can  be  sent  to  LPT3  to  yield  Epson  FX-80  quality  output  on  a  Postscript 
printer. 

Drives 

The  DOS  command  FORMAT  A:  /S  works  only  if  the  current  working  directory  contains  DOS  files.  This 
is  usually  Drive  C  and  sometimes  Drive  A. 

Drive  A  The  Sun386i  3.5-inch  diskette  drive,  used  for  reading  PC  format  diskettes  onto  the 

hard  disk  and  writing  data  to  be  stored  on  floppy.  Drive  A  is  not  accessible  across  a 
network. 

An  optional  5,25-inch  diskette  drive.  Same  restrictions  as  Drive  A. 

A  virtual  disk  stored  in  the  “/pc/C:  file.  Files  written  to  Drive  C  cannot  be  accessed 
from  the  SunOS  operating  system.  Drive  C  is  generally  intended  for  storage  of 
applications  and  copy  protected  software  but  not  data.  To  DOS,  drive  C  is  a  20- 
megabyte  drive.  You  can  install  copy-protected  software  on  drive  C,  but  not  on  other 
drives. 

Drives  D  through  S  Equivalents  of  the  SunOS  operating  system  directories.  They  can  be  accessed  from 
either  the  DOS  or  SunOS  operating  systems,  and  can  contain  any  number  of  files  and 
other  directories.  The  SunOS  directories  referenced  by  DOS  drives  other  than  D,  H, 
and  R  (described  below)  are  user-defined  (using  the  DOS  EXTEND  command). 


Drive  B 
Drive  C 
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Drive  D  The  current  SunOS  directory  when  the  DOS  window  was  opened.  May  sub¬ 
sequently  be  changed  to  any  other  directory. 

Drive  H  The  home  directory  of  the  user  who  opened  the  window.  May  subsequendy 
be  changed  to  any  directory  in  the  user’s  home  directory  tree. 

Drive  R  Initially  equivalent  to  the  root  directory  of  the  SunOS  operating  system. 

File  Sharing  between  SunOS  and  DOS 

File  names  under  DOS  consist  of  8  characters,  a  period,  and  a  3  character  extension.  When  a  SunOS 
filename  does  not  comply  with  these  rules,  its  name  is  modified  by  placing  a  tilde  Q  in  an  appropriate  loca¬ 
tion  so  that  the  file  name  conforms  to  DOS  specifications  while  remaining  unique.  It  is  recommended  that 
filenames  conform  to  DOS  requirements  for  files  to  be  used  in  both  the  SunOS  and  DOS  operating  systems. 

Because  the  SunOS  and  DOS  operating  systems  use  different  conventions  for  RETURN  characters, 
dos2unix  and  unix2dos  are  provided  to  convert  text  files  between  the  two  formats. 

Command  Sharing  between  SunOS  and  DOS 

The  /etc/dos/unix  directory  contains  a  list  of  SunOS  commands  accessible  from  DOS.  Other  SunOS  com¬ 
mands  not  in  this  list  can  be  executed  from  DOS  with  the  command  ‘unix  command",  SunOS  commands 
always  use  SunOS  filename  conventions  and  DOS  commands  always  use  DOS  filename  conventions, 
regardless  of  whether  either  type  of  command  is  executed  from  the  SunOS  or  DOS  operating  system.  Only 
DOS  commands  can  use  drives  A  and  C. 

OPTIONS 

-b  Boots  (loads)  IX)S  and  opens  a  window  using  the  AUTOEXEC.BAT  and  CONFIG.SYS  files  instead 
of  7pc/.quickpc.  A  DOS  sign-on  message  is  displayed  in  the  window. 

-s  Boot  DOS  and  save  a  new  .quickpc  unless  C;AUTOEXEC.BAT,  C:CONFIG.SYS,  or 
/etc/dos/defaults/rom  has  a  date  newer  than  the  .quickpc  file  (see  the  — s  option). 

-p  config 

Loads  an  alternate  file  instead  of  setup.pc. 

-q  Forces  dos  to  read  settings  from  the  .quickpc  file  (as  specified  in  setup.pc)  even  if 
C: AUTOEXEC.BAT,  C;CONFIG,SYS,  or  /etc/dos/defaults/rom  have  been  updated  since  you  last 
typed  dos  -s. 

-s  Boot  DOS  and  save  a  new  .quickpc  file  under  the  name  specified  on  the  SAVE  line  in 
7pc/setup.pc.  Use  this  option  after  making  changes  to  drive  C’s  AUTOEXEC.BAT  or 
CONFIG.SYS.  Exits  DOS  after  saving  the  .quickpc  file. 

-update 

Gives  you  a  new  drive  C  and  a  new  setup.pc  using  the  settings  from  /etc/dos/defaults/C:  and 
/etc/dos/deraults/setup.pc,  respectively. 

-w  Runs  DOS  text-only  commands  and  applications  in  the  current  SunView  Commands  window. 

-c  command 

Executes  the  given  DOS  command  in  the  newly  created  window.  If  you  use  the  -c  option,  -c  and 
the  command  that  follows  it  must  be  the  last  items  on  the  command  line. 

ENVIRONMENT 

DOS_LOCKING  This  environment  variable  determines  which  locking  service  is  used  to  lock  drive  C  for 
write  access.  If  it  is  set  to  on,  DOS  uses  the  locking  service  on  the  server  where  the  home 
directory  is  located.  This  locks  drive  C  for  access  from  any  DOS  window  on  the  net¬ 
work.  If  it  is  set  to  off,  DOS  uses  the  local  system’s  locking  service.  This  locks  drive  C 
only  for  access  from  DOS  windows  running  on  the  local  system.  The  default  is  on. 
Some  servers  (for  example,  some  VAXAJltrix  systems)  do  not  provide  an  NFS  locking 
service.  For  home  directories  stored  on  these  servers,  set  the  variable  to  off  to  avoid  an 
error  message  when  a  DOS  window  starts  up. 
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DOS_PRINTER  The  value  of  this  environment  variable  indicates  the  timeout  (in  seconds)  for  printing.  A 
value  of  20  (the  default)  indicates  that  jobs  will  be  sent  to  the  UNIX  print  spooler  after  20 
seconds  of  no  printing  activity  from  DOS  to  that  printer.  A  value  of  0  indicates  that  the 
spooler  must  be  flushed  manually  from  the  menu  in  the  window. 

DOSLOOKUP 

If  on,  this  environment  variable  indicates  that  a  command  should  be  tried  as  a  DOS  com¬ 
mand  if  not  recognized  by  the  SunOS  system.  If  DOS  supports  the  command,  a  DOS 
window  is  created  and  the  command  executed  in  that  window.  If  the  command  does  not 
exist,  the  normal  SunOS  error  message  results. 


FILES 

/etc/dos/unix 

/etc/  dos/  defaults/.quickpc 

/etc/ dos/ defaults/setup  .pc 

/etc/dos/defaults/boar  ds.pc 

/etc/  dos/defaults/C ; 

7pc/autoexec.bat 

C:AUTOEXEC.BAT 

D:AUTOEXEC.BAT 

C:CONFIG.SYS 

7pc/setup.pc 

7pc/.quickpc 

7pc/C: 


Files  in  this  directory  indicate  which  SunOS  commands  are  accessible  from 
DOS. 

Default  .quickpc  file  copied  into  a  user’s  home  PC  directory  (7pc)  the  first 
time  a  DOS  window  is  started.  Not  used  by  DOS  in  this  location. 

Default  setup.pc  file  copied  into  a  user’s  home  DOS  directory  (“/pc)  the  first 
time  a  DOS  window  is  started.  Not  used  by  DOS  in  this  location. 

Stores  information  about  IBM  PC/XT/AT-compatible  boards  installed  in  your 
system. 

Default  drive  C  file  copied  into  a  user’s  home  PC  directory  the  first  time  a 
DOS  window  is  started. 

Contains  drive  assignments,  search  paths,  and  other  startup  commands. 
Searched  after  C; AUTOEXEC.BAT  and  D:  AUTOEXEC.BAT. 

Contains  commands  to  access  system  printers  and  special  drives.  You 
should  not  need  to  change  the  AUTOEXEC.BAT  on  drive  C.  Put  your 
changes  in  the  AUTOEXEC.BAT  on  drive  H  (in  your  home  directory). 
C:AUTOEXEC.BAT  is  not  accessible  from  the  SunOS  system. 

If  an  AUTOEXEC.BAT  file  exists  in  the  current  directory,  DOS  tries  execute 
faster  running  C:AUTOEXEC.BAT. 

Specifies  device  drivers  and  other  system  parameters.  C:CONFIG.SYS  is 
not  accessible  from  the  SunOS  system. 

Defines  printers,  standard  PC  devices,  and  drive  C.  One  or  more  of  these 
files  may  exist,  under  various  names  which  you  assign. 

An  image  of  DOS  as  last  saved  with  dos  -s,  including  all  DOS  environment 
variables  and  drivers  that  were  in  effect  at  that  time.  DOS  normally  reads 
this  file  at  startup. 

A  user’s  personal  copy  of  drive  C. 


DIAGNOSTICS 

Cannot  save  filename  quick-start  file. 

The  dos  command  was  unable  to  save  the  specified  quick-start  file.  Check  the  SAVE  setting  in 
your  PC  setup  file  (normally  "/pc/setup.pc).  Also  check  file  access  permissions  on  the  specified 
quick-start  file. 


Cannot  load  filename  quick-start  file. 

dos  was  unable  to  read  the  specified  quick-start  file.  Check  the  SAVE  setting  in  your  setup.pc 
file.  Also  check  file  access  permissions  on  the  specified  quick-start  file. 


Possible  software  incompatibility.  Unsupported  286  instruction  instruction  at  address. 

Possible  software  incompatibility.  Unsupported  386  instruction. 

Possible  software  incompatibility.  Segment  wrap. 

Possible  software  incompatibility.  Two-byte  opcode . 

The  application  you  are  running  was  written  specifically  for  80286  or  80386  machines. 
Software  run  from  a  DOS  window  must  be  compatible  with  8086  systems. 
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Copying  default  configuration  files  into  your  home  directory . 

This  is  the  first  time  you  have  run  the  dos  command.  A  7pc  directory  is  being  set  up,  and 
DOS -related  files  are  being  copied  into  it. 

Another  DOS  window  already  has  access  to  device 
IRQ  level  number  is  still  in  use  by  another  DOS  window. 

Your  PC  configuration  file  (normally  7pc/setup.pc)  is  requesting  access  to  a  physical  device  that 
another  DOS  window  is  using. 

Port  number  number  out  of  range  for  board  board. 

The  port  number  specified  in  the  /etc/dos/defaults/boards.pc  is  invalid. 

IRQ  value  number  out  of  range  for  board  board. 

The  interrupt  level  specified  in  the  /etc/dos/defaults/boards.pc  is  invalid. 

IRQ  level  number  is  in  use  by  a  Unix  driver . 

There  is  a  Unix  driver  servicing  the  board  you  are  trying  to  attach  to  DOS.  You  are  using  the 
wrong  IRQ  level  or  you  should  use  the  driver  instead. 

Interrupt  level  number  is  used  by  DOS  to  support  device 

The  interrupt  level  specified  in  the  ^tc/dos/defaults/boards.pc  conflicts  with  an  interrupt  value 
currently  being  used  by  either  a  physical  or  emulated  DOS  device. 

I/O  address  range  address-address  requested  for  name  board  already  in  use  by  device . 

The  address  range  specified  in  the  /etc/dos/defaults/boards.pc  conflicts  with  range  currently 
being  used  by  either  a  physical  or  emulated  DOS  device. 

Cannot  share  device  with  a  hardware  interrupt  or  DMA  channel . 

A  shared  device  specified  in  the  /etc/dos/defaults/boards.pc  was  also  assigned  an  interrupt  level 
in  this  file.  Shared  devices  cannot  be  assigned  interrupt  levels. 

Couldn’t  find  name  board  in  boards.pc . 

A  file  specified  in  the  PC  setup  file  (normally  7pc/setup.pc)  is  not  listed  in  the 
/etc/dos/defaults/boards.pc  file.  Check  the  setup.pc  file,  or  add  an  entry  for  the  board  in 
boards.pc. 

ROM  is  newer  than  .quickpc.  Rebooting  prograw  /iame. 

Save  a  new  .quickpc  file  by  issuing  the  command  dos  -s. 

Warning:  Your  personal  drive  C  (pathname)  is  not  protected  against  simultaneous  acce^  by  more 
than  one  workstation.  Ask  your  system  administrator  to  upgrade  server  to  use  the  lock  manager. 
Until  your  home  directory  server  is  updated  with  this  program,  do  not  use  program_name  when  you 
are  logged  into  more  than  one  workstation. 

The  system  on  the  network  where  your  drive  C  is  stored  has  not  protected  the  drive  against  access 
by  DOS  windows  in  other  workstations  on  the  network.  This  usually  means  that  the  server  where 
your  home  directory  is  stored  does  not  provide  an  NFS  locking  service.  To  avoid  this  error  mes¬ 
sage,  set  the  environment  variable  DOS_LOCKING  to  off. 

SEE  ALSO 

dos2unix(l),  unix2dos(l) 

Sun386i  User’s  Guide 
Sun386i  Advanced  Skills 
Sun  MS-DOS  Reference  Manual 
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NAME 

dos2unix  -  convert  text  file  from  DOS  format  to  ISO  format 
SYNOPSIS 

dos2unix  [  -ascii  ]  [  -iso  ]  [  -7  ]  originalfile  convertedfile 
AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0j[:  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

dos2unix  converts  characters  in  the  DOS  extended  character  set  to  the  corresponding  ISO  standard  charac¬ 
ters. 

This  command  can  be  invoked  fi-om  either  DOS  or  SunOS.  However,  the  filenames  must  conform  to  the 
conventions  of  the  environment  in  which  the  command  is  invoked. 

If  the  original  file  and  the  converted  file  are  the  same,  dos2unix  will  rewrite  the  original  file  after  convert¬ 
ing  it. 

OPTIONS 

-ascii  Removes  extra  carriage  returns  and  converts  end  of  file  characters  in  DOS  format  text  files  to  con¬ 
form  to  SunOS  requirements. 

-iso  This  is  the  default.  It  converts  characters  in  the  DOS  extended  character  set  to  the  corresponding 
ISO  standard  characters. 

-7  Convert  8  bit  DOS  graphics  characters  to  7  bit  space  characters  so  that  SunOS  can  read  the  file. 
DIAGNOSTICS 

File  filename  not  found,  or  no  read  permission 

The  input  file  you  specified  does  not  exist,  or  you  do  not  have  read  permission  (check  with  the 
SunOS  Is  -1  command). 

Bad  output  filename  filename,  or  no  write  permission 

The  output  file  you  specified  is  either  invalid,  or  you  do  not  have  write  permission  for  that  file  or 
the  directory  that  contains  it.  Check  also  that  the  drive  or  diskette  is  not  write-protected. 

Error  while  writing  to  temporary  file 

An  error  occurred  while  converting  your  file,  possibly  because  there  is  not  enough  space  on  the 
current  drive.  Check  the  amount  of  space  on  the  current  drive  using  the  DIR  command.  Also  be 
certain  that  the  default  diskette  or  drive  is  write-enabled  (not  write-protected).  Note  that  when  this 
error  occurs,  the  original  file  remains  intact. 

Could  not  rename  temporary  file  to 
Translated  temporary  file  name  =  filename. 

The  program  could  not  perform  the  final  step  in  converting  your  file.  Your  converted  file  is  stored 
under  the  name  indicated  on  the  second  line  of  this  message. 

SEE  ALSO 

dos(l),  unix2dos(l) 
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NAME 

du  -  display  the  number  of  disk  blocks  used  pCT  directory  or  file 
SYNOPSIS 

du  [ -s  ]  [ -a  ]  [filename  ,,,] 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/du  [  -s  ]  [  -a  ]  [  ]  [filename . . .  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
io  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

du  gives  the  number  of  kilobytes  contained  in  all  files  and,  recursively,  directories  within  each  specified 
directory  or  file  filename.  If filename  is  missing,  (the  current  directory)  is  used. 

A  file  which  has  multiple  links  to  it  is  only  counted  once. 

SYSTEM  V  DESCRIPTION 

The  System  V  version  of  du  gives  the  number  of  512-byte  blocks  rather  than  the  number  of  kilobytes. 
OPTIONS 

-s  Only  display  the  grand  total  for  each  of  the  specified  filenames. 

~a  Generate  an  entry  for  each  file. 

Entries  are  generated  only  for  each  directory  in  the  absence  of  options. 

SYSTEM  V  OPTIONS 

-r  The  System  V  version  of  du  is  normally  silent  about  directories  that  cannot  be  read,  files  that  can¬ 
not  be  opened,  etc.  The  -r  option  will  cause  du  to  generate  messages  in  such  instances. 

EXAMPLE 

Here  is  an  example  of  using  du  in  a  directory.  We  used  the  pwd(l)  command  to  identify  the  directory, 
then  used  du  to  show  the  usage  of  all  the  subdirectories  in  that  directory.  The  grand  total  for  the  directory 
is  the  last  entiy  in  the  display: 

%  pwd 

/usr/ralph/misc 
%  du 

5  ./jokes 

33  ./squash 

44  ./tech.papers/lpr.do€ument 

217  ./tech.papers/new.manager 

401  ./tech.papers 

144  ./memos 

80  ./letters 

388  ./window 

93  ./messages 

15  ./usefuLnews 

1211  . 

% 


SEE  ALSO 

df(lV),  pwd(l),  quot(8) 

BUGS 

Filename  arguments  that  are  not  directory  names  are  ignored,  unless  you  use  -a . 

If  there  are  too  many  distinct  linked  files,  du  will  count  the  excess  files  more  than  once. 
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NAME 

echo  ~  echo  arguments  to  the  standard  output 

SYNOPSIS 

echo  [  ~n  ]  [  argument . . .  ] 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/echo  argument . . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4,1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

echo  writes  its  arguments  on  the  standard  output.  Arguments  must  be  separated  by  SPACE  characters  or 
TAB  characters,  and  terminated  by  a  NEWLINE. 

echo  is  useful  for  producing  diagnostics  in  shell  programs  and  for  writing  constant  data  on  pipes.  If  you 
are  using  the  Bourne  shell  (sh(l)),  you  can  send  diagnostics  to  the  standard  error  file  by  typing: 
echo...  >&2 

SYSTEM  V  DESCRIPTION 

Note:  If  /usr/Sbin  is  ahead  of  /usr/bin  in  the  Bourne  shell’s  search  path,  its  built-in  echo  command  mimics 
the  System  V  version  of  echo  as  described  here. 

echo  also  understands  C  -like  escape  conventions;  beware  of  conflicts  with  the  shell’s  use  of 
\b  BACKSPACE 

\c  Print  line  without  NEWLINE 

\f  FORMFEED 

\n  NEWLINE 

\r  RETURN 

\t  TAB 

\v  vertical  TAB 

W  backslash 

\n  the  8-bit  character  whose  ASCII  code  is  the  1-,  2-,  3-  or  4-digit  octal  number  n.  The  first 
digit  must  be  zero. 

OPTIONS 

-n  Do  not  add  the  NEWLINE  to  the  output. 

SEE  ALSO 

sh(l) 
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NAME 

ed,  red  -  basic  line  editor 
SYNOPSIS 

ed  [  -  ]  [  -sx  ]  [  “p  string  ]  [filename  ] 
red  [  -  ]  [  -sx  ]  [  -p  string  ]  [filename  ] 

DESCRIPTION 

ed  is  the  most  basic  line  editor  of  the  UNIX  system.  Although  superseded  by  ex(l)  and  vi(l)  for  most  pur¬ 
poses,  ed  is  still  used  by  various  system  utilities. 

ed  operates  on  a  copy  of  filename,  called  a  buffer,  and  overwrites  a  file  only  when  you  issue  the  w  (write) 
command,  ed  provides  line  oriented  editing  commands  to  display  or  change  lines,  to  insert  and  delete  lines 
from  the  buffer,  to  move  or  copy  lines  within  the  buffer,  or  to  substitute  character  strings  within  lines. 

red  is  a  restricted  version  of  ed.  It  will  only  allow  editing  of  files  in  the  current  directory,  and  prohibits 
executing  commands  using  Icommand.  Attempts  to  bypass  these  restrictions  result  in  an  error  message. 

OPTIONS 

-s  Suppress  priming  of  character  counts  (by  e,  r,  and  w  commands),  diagnostics  (by  e  and  q  com¬ 

mands),  and  the  !  prompt  (after  a  !  command).  Also,  suppress  printing  the  ?  diagnostic  before 
overwriting  unsaved  changes  in  the  buffer, 

“X  Edit  an  encrypted  file  (see  crypt(l)  for  details). 

-p  string  Use  string  as  the  editing  prompt  in  command  mode. 

USAGE 

Command  Structure 

ed  commands  have  a  simple  and  regular  structure.  They  consist  of  an  optional  address,  or  two  optional 
addresses  separated  by  a  comma  or  semicolon,  then  a  single-character  command,  which  may  be  followed 
by  a  parameter  for  that  command : 

[address  [  ^ address  ]]  command  [parameter  ] 

If  only  one  address  is  specified,  operations  are  performed  on  that  line.  If  two  addresses  are  specified,  ed 
performs  the  operation  on  the  inclusive  range  of  lines.  Commands  that  requires  an  address  use  certain 
addresses  by  default,  typically  the  address  of  the  current  line. 

For  example,  l,10p  means  “print  (display)  lines  1  through  10”  (two  addresses),  5a  means  “append  text 
after  line  5”  (one  address),  and  d  means  “delete  the  current  line”  (no  address  with  the  current  line  used  as 
default).  The  meaning  of  parameter  varies  for  each  operation  —  for  the  move  (m)  and  transfer  (t)  opera¬ 
tions,  for  instance,  it  is  the  line  that  the  addressed  lines  are  to  be  moved  to  or  transferred  after.  For  reading 
(r)  and  writing  (w)  a  file,  parameter  specifies  the  name  of  the  file  that  is  to  be  read  or  written. 

ed  is  extremely  terse  in  its  interaction  with  the  user.  Its  normal  response  to  most  problems  is  simply  a 
question  mark  (?).  This  may  happen  when  ed  cannot  find  a  specified  line  in  the  buffer,  or  if  a  search  for  a 
regular  expression  fails  in  a  substitute  (s)  command.  The  h  command  prints  a  somewhat  more  complete 
diagnostic  for  the  most  recent  error  encountered;  the  H  command  requests  that  the  diagnostic  be  printed  for 
all  eirors. 

Addresses 

Lines  can  be  addressed  in  several  ways: 

nnn  By  line  number.  Lines  in  the  buffer  are  numbered  relative  to  the  start  of  the  buffer.  When 
displayed,  line  numbers  are  not  physically  present  with  the  text  of  the  file  or  buffer, 

$  The  last  line  of  the  buffer. 

.  The  current  line,  ed  keeps  track  of  the  line  on  which  you  last  performed  an  operation.  This  line  is 

called  the  current  line.  You  can  address  this  line  by  typing  a  “dot”  character. 
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±n  By  relative  line  number.  Address  the  line  number  that  is  n  lines  higher,  or  n  lines  lower  than  the 
current  line. 

'c  Address  the  line  marked  with  the  mark  character  c,  which  must  be  a  lower-case  letter.  Lines  are 
marked  with  the  k  command,  described  below. 

/RE/  An  RE  is  Si  Regular  Expression,  described  under  Regular  Expressions  below.  When  enclosed  by 
slashes,  RE  addresses  the  first  line  found  by  searching  for  a  matching  string.  The  search  proceeds 
forward  from  the  line  following  the  current  line,  and  wr^s  through  the  beginning  of  the  buffer  to 
include  all  preceding  lines,  as  well  as  the  current  line. 

?RE?  An  RE  enclosed  in  question  marks  addresses  the  first  line  containing  a  match  found  by  searching 
backward  from  the  line  preceding  the  current  line.  The  search  wraps  through  the  end  of  the  buffer 
to  include  all  lines  following  the  current  line  (in  reverse  order),  as  well  as  the  current  line. 

address±n 

An  address  followed  by  a  plus  sign  (+)  or  a  minus  sign  (-),  followed  by  a  decimal  number, 
specifies  that  address  plus  or  minus  the  indicated  number  of  lines.  (The  plus  sign  may  be  omit¬ 
ted.)  If  the  address  is  omitted,  the  current  line  is  used  as  the  base.  For  example,  ‘31-3’  addresses 
line  28  in  the  buffer. 

address± 

If  an  address  ends  with  *+’  or  then  1  is  added  to  or  subtracted  from  the  address,  respectively. 
As  a  consequence  of  this  rule  and  the  previous  rule,  the  address  refers  to  the  line  preceding  the 
current  line.  (To  maintain  compatibility  with  earlier  versions  of  ed,  the  character  is  equivalent 
to  ‘-’.)  Trailing  *+'  and  characters  have  a  cumulative  effect,  so  ‘ — ’  refers  to  the  current  line, 
less  2. 

,  By  itself,  a  comma  stands  for  the  address  pair 
;  A  semicolon  by  itself  stands  for  the  pair 

By  default  for  a  given  command.  If  you  do  not  specify  an  address  for  a  command  to  operate  on,  a 
command  that  requires  an  address  supplies  one  by  default.  This  is  typically  the  current  line. 

A  pair  of  addresses  separated  by  a  comma  signifies  an  inclusive  range  of  lines,  and  the  current  line  is  not 
changed  unless  the  command  changes  it.  When  addresses  are  separated  by  a  semicolon,  however,  the 
current  line  is  set  to  the  address  preceding  the  semicolon  before  any  subsequent  addresses  are  interpreted. 
This  feature  can  be  used  to  determine  the  starting  line  for  forward  and  backward  searches  using  7’,  and  ‘?’. 

The  second  address  of  any  two-address  sequence  must  correspond  to  a  line  that  occurs  later  in  the  buffer 
than  that  of  the  first  address. 

Regular  Expressions 

ed  supports  a  limited  form  of  regular-expression  notation,  which  can  be  used  in  a  line  address  to  specify 
lines  by  content.  A  regular  expression  (RE)  specifies  a  set  of  character  strings  to  match  against  —  such  as 
“any  string  containing  digits  5  through  9”  or  “only  lines  containing  uppercase  letters.”  A  member  of  this  set 
of  strings  is  said  to  be  matched  by  the  regular  expression.  Regular  expressions  or  patterns  are  used  to 
address  lines  in  the  buffer  (see  Addresses  ,  above),  and  also  for  selecting  strings  to  be  replaced  using  the  s 
(substitute)  command. 

Where  multiple  matches  are  present  in  a  line,  a  regular  expression  matches  the  longest  of  the  leftmost 
matching  strings. 

Regular  expressions  can  be  built  up  from  the  following  “single-character”  RE’s: 
c  Any  ordinary  character  not  listed  below.  An  ordinary  character  matches  itself. 

\  Backslash.  When  followed  by  a  special  character,  the  RE  matches  the  “quoted”  character.  A 

backslash  followed  by  one  of  <,  >,  (, ),  {,  or  },  represents  an  operator  in  a  regular  expression,  as 
described  below. 

Dot.  Matches  any  single  character  except  NEWLINE. 
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As  the  leftmost  character,  a  caret  (or  circumflex)  constrains  the  RE  to  match  the  leftmost  portion 
of  a  line.  A  match  of  this  type  is  called  an  "anchored  match”  because  it  is  "anchored”  to  a  specific 
place  in  the  line.  The  ''  character  loses  its  special  meaning  if  it  appears  in  any  position  other  than 
the  start  of  the  RE. 

$  As  the  rightmost  character,  a  dollar  sign  constrains  the  RE  to  match  the  rightmost  portion  of  a  line. 
The  $  character  loses  its  special  meaning  if  it  appears  in  any  position  other  than  at  the  end  of  the 
RE. 

^RE$  The  construction  ^RE  $  constrains  the  RE  to  match  the  entire  line. 

\<  The  sequence  \<  in  an  RE  constrains  the  one-character  RE  immediately  following  it  only  to  match 
something  at  the  beginning  of  a  “word”;  that  is,  either  at  the  beginning  of  a  line,  or  just  before  a 
letter,  digit,  or  underline  and  after  a  character  not  one  of  these. 

\>  The  sequence  \>  in  an  RE  constrains  the  one-character  RE  immediately  following  it  only  to  match 
something  at  the  end  of  a  "word.” 

[  c . . .  ]  A  nonempty  string  of  characters,  enclosed  in  square  brackets  matches  any  single  character  in  the 
string.  For  example,  [abcxyz]  matches  any  single  character  from  the  set  ‘abcxyz’.  When  the  first 
character  of  the  string  is  a  caret  (*),  then  the  RE  matches  any  character  except  NEWLINE  and  those 
in  the  remainder  of  the  string.  For  example,  ‘["45678]’  matches  any  character  except  ‘45678’.  A 
caret  in  any  other  position  is  interpreted  as  an  ordinary  character. 

[  ]  c . . .  ]  The  right  square  bracket  does  not  terminate  the  enclosed  string  if  it  is  the  first  character  (after  an 
initial  if  any),  in  the  bracketed  string.  In  this  position  it  is  treated  as  an  ordinary  character. 

[  l-r  ]  The  minus  sign,  between  two  characters,  indicates  a  range  of  consecutive  ASCII  characters  to 
match.  For  example,  the  range  ‘[0-9]’  is  equivalent  to  the  string  ‘[0123456789]’.  Such  a  brack¬ 
eted  string  of  characters  is  known  as  a  character  class.  The  ’  is  treated  as  an  ordinary  character 
if  it  occurs  first  (or  first  after  an  initial ")  or  last  in  the  string. 

d  Delimiter  character.  The  character  used  to  delimit  an  RE  within  a  command  is  special  for  that 
command  (for  example,  see  how  /  is  used  in  the  g  command,  below). 

The  following  rules  and  special  characters  allow  for  constructing  RE’s  from  single-character  RE’s: 

A  concatenation  of  RE’s  matches  a  concatenation  of  text  strings,  each  of  which  is  a  match  for  a 
successive  RE  in  the  search  pattern. 

*  A  single-character  RE,  followed  by  an  asterisk  (♦)  matches  zero  or  more  occurrences  of  the 
single-character  RE.  Such  a  pattern  is  called  a  closure.  For  example,  [a-z][a-z]*  matches  any 
string  of  one  or  more  lower  case  letters. 

\{m\} 

\{m,\} 

\{m,n\}  A  one-character  RE  followed  by  \{wz\},  or  \{m,n\}  is  an  RE  that  matches  a  range  of 

occurrences  of  the  one-character  RE,  The  values  of  m  and  n  must  be  nonnegative  integers  less  than 
256;  \{m\}  matches  exactly  m  occurrences;  matches  at  least  m  occurrences; 

matches  any  number  of  occurrences  between  m  and  «,  inclusively.  Whenever  a  choice  exists,  the 
RE  matches  as  many  occurrences  as  possible. 

\(. ,  .\)  An  RE  enclosed  between  the  character  sequences  \(  and  \)  matches  whatever  the  unadorned  RE 
matches,  but  saves  the  string  matched  by  the  enclosed  RE  in  a  numbered  substring  register.  There 
can  be  up  to  nine  such  substrings  in  an  RE,  and  parenthesis  operators  can  be  nested. 

\n  Match  the  contents  of  the  nth  substring  register  from  the  current  RE.  This  provides  a  mechanism 

for  extracting  matched  substrings.  For  example,  the  expression  "\(„*\)\1$  matches  a  line  consist¬ 
ing  entirely  of  two  adjacent  non-null  appearances  of  the  same  string.  When  nested  parenthesized 
substrings  are  present,  n  is  determined  by  counting  occurrences  of  \(  starting  from  the  lefL 

/  /  The  null  RE  (/  /)  is  equivalent  to  the  last  RE  encountered. 
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Commands 

The  commands  a  for  append,  c  for  change ,  and  i  for  insert,  allow  you  to  add  new  text  to  the  buffer.  While 
accepting  new  text,  ed  is  said  to  be  in  input  mode.  While  in  input  mode,  no  commands  are  recognized;  all 
character  input  is  inserted  into  the  buffer.  To  exit  from  input  mode,  enter  a  dot  (.)  on  a  line  by  itself;  ed 
then  reverts  to  command  mode.  Or,  you  can  interrupt  ed  (typically  with  CTRL-C),  in  which  case  it  displays 
a  ?  and  returns  to  command  mode. 

Commands  may  accept  zero,  one,  or  two  addresses.  Commands  that  accept  no  addresses  regard  the  pres¬ 
ence  of  an  address  as  an  error.  Commands  that  accept  one  or  two  addresses  assume  default  addresses  when 
too  few  addresses  are  given;  if  more  addresses  are  given  than  such  a  command  requires,  only  the  last  ones 
are  used. 

In  the  following  list  of  ed  commands,  the  default  addresses  are  shown  in  parentheses;  the  parenthesized 
addresses  are  not  part  of  the  command. 

It  is  generally  illegal  for  more  than  one  command  to  appear  on  a  line.  However,  any  command  (except  e,  f, 
r,  or  w)  may  be  followed  by  1,  n,  or  p  in  which  case  the  current  line  is  either  listed,  number^  or  printed, 
respectively. 

text 

,  Append  text  Add  lines  of  text  into  the  buffer  after  the  addressed  line.  The  resulting  current  line 

is  the  last  line  of  input,  or  the  addressed  line  if  no  text  is  entered.  Address  0  is  legal  for  this  com¬ 
mand,  in  which  case  the  text  is  placed  at  the  beginning  of  the  buffer.  The  maximum  number  of 
characters  per  input  line  (from  a  terminal)  is  256.  including  the  final  NEWLINE. 

text 

Change  lines.  Delete  the  addressed  lines,  and  then  accept  lines  of  text  to  replace  them,  c  accepts 
one  or  two  addresses;  the  default  is  the  current  line.  The  resulting  current  line  is  the  last  line  of 
input,  or  the  line  preceding  the  deleted  lines  if  no  text  is  entered. 

^■”^d  Delete  the  addressed  lines  from  the  buffer,  d  accepts  one  or  two  addresses;  the  default  is  the 
current  line.  The  resulting  current  line  is  the  line  following  the  last  one  deleted;  if  the  deleted 
lines  were  at  the  end  of  the  buffer,  the  new  last  line  is  the  resulting  current  line. 

e  filename 

Edit  a  file.  Delete  the  entire  contents  of  the  buffer,  and  then  read  in  the  named  file.  The  resulting 
current  line  is  the  last  line  of  the  buffer,  e  reports  the  number  of  characters  read  into  the  buffer, 
and  sets  filename  to  be  the  current  file  (for  use  as  a  default  filename  in  subsequent  commands).  If 
no  filename  is  given,  the  current  filename,  if  any,  is  used  (see  the  f  command,  below).  If  filename 
is  replaced  by  a  shell  (sh(l))  command  prefaced  with  a  *!’,  the  shell  command  is  executed  and  its 
output  is  read  into  the  buffer  after  the  current  line.  Such  a  shell  command  is  not  used  as  the 
current  filename,  e  displays  a  ?  if  the  buffer  has  not  been  written  out  since  the  last  change  made  — 
another  e  command  in  response  to  the  ?  forces  the  command  to  take  effect. 

E  filename 

The  E  command  is  like  e,  except  that  the  editor  does  not  check  for  changes  to  the  buffer  since  the 
last  w  command  was  performed. 

f  filename 

Display  or  set  the  current  filename.  If  filename  is  given  as  an  argument,  the  file  (f)  command 
changes  the  current  filename  to  filename;  otherwise,  it  prints  the  current  filename. 

gf RE f command-list 

The  global  (g)  command  performs  command-list  on  all  lines  in  the  range  of  addresses  that  match 
RE.  ed  executes  command-list  for  each  matching  line  in  succession,  setting  the  current  line  to 
each  in  turn,  command-list  can  contain  a  single  command,  or  it  can  be  continued  across  input 
lines,  with  one  ed  command  per  line,  by  escaping  all  but  the  last  NEWLINE  with  a  \  character. 
Operations  that  place  ed  into  input  mode  (a,  i,  and  c),  are  permitted  in  command-list;  the  final 
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terminating  text  input  may  be  omitted  if  it  is  the  last  line  of  the  command-list,  g,  G,  v,  and  V 
commands,  however,  are  not  permitted.  An  empty  command-list  is  equivalent  to  the  p  command. 

G/RE/ 

The  interactive  G  (Global)  command,  selects  all  lines  that  match  the  given  RE.  Then,  each 
selected  line  is  made  current,  and  any  one  command  (other  than  one  of  the  a,  c,  i,  g,  G,  v,  and  V 
commands)  can  be  performed  upon  that  line.  A  NEWLINE  acts  as  a  null  command;  an  &  reexe¬ 
cutes  the  most  recent  command.  Commands  entered  during  execution  of  the  G  command  can 
address  and  affect  lines  other  than  the  current  line.  The  G  command  can  be  terminated  by  an 
interrupt  (typically  CTRL-D). 

h  Help.  Display  a  short  error  message  that  explains  the  reason  for  the  most  recent  ?  diagnostic. 

H  Automatic  printing  of  help  diagnostics.  Toggle  between  printing  the  ?  diagnostic,  or  automati¬ 

cally  printing  diagnostic  messages  as  well. 

(.); 

text 

,  Insert  Text.  Insert  the  given  text  into  the  buffer,  above  the  addressed  line,  i  accepts  one  address; 

the  default  is  the  current  line.  The  resulting  current  line  is  the  last  line  of  input;  if  no  text  is  input, 
it  is  the  line  just  before  the  addressed  line.  This  command  differs  from  the  a  command  only  in  the 
placement  of  the  input  text;  Address  0  is  not  allowed  for  this  command.  The  maximum  number  of 
characters  that  may  be  entered  from  a  terminal  is  256  per  line  (including  the  NEWUNE  character). 

Join  Lines.  Remove  the  NEWLINE  character  from  between  the  two  addressed  lines.  The  defaults 
are  the  current  line  and  the  line  following.  If  exactly  one  address  is  given,  this  command  does 
nothing.  The  joined  line  is  the  resulting  current  line. 

Mark  the  addressed  line  with  the  name  c,  a  lower-case  letter.  The  address-form,  'c,  addresses  the 
line  marked  by  c.  k  accepts  one  address;  the  default  is  the  current  line.  The  current  line  is  left 
unchanged. 

^■”^1  List  nonprinting  characters.  Print  the  addressed  lines  in  an  unambiguous  way:  a  few  nonprinting 
charactt^rs,  such  as  TAB  and  BACKSPACE  are  represented  by  visually  mnemonic  overstrikes.  All 
other  nonprinting  characters  are  shown  in  octal,  with  long  lines  folded.  I  accepts  one  or  two 
addresses;  the  default  is  the  current  line.  The  resulting  current  line  is  the  last  line  printed.  An  1 
command  may  be  appended  to  any  command  other  than  e,  f,  r,  or  w. 

maddress 

Move  addressed  lines  to  just  after  address.  Address  0  is  legal,  and  moves  the  addressed  line(s)  to 
the  beginning  of  the  file.  An  error  results  if  address  falls  within  the  range  of  lines  to  move,  m 
accepts  two  addresses  to  specify  a  range  of  lines  to  move;  the  default  is  the  current  line.  The 
resulting  current  line  is  the  last  of  the  moved  lines. 

Number  the  displayed  lines.  Print  the  addressed  lines,  preceding  each  with  its  line  number  and  a 
TAB  character,  n  accepts  one  or  two  addresses;  the  default  is  the  current  line.  The  resulting 
current  line  is  the  last  line  printed.  The  n  command  can  be  appended  to  any  command  other  than 
e,  f,  r,  or  w. 

Print  the  addressed  lines,  p  accepts  one  or  two  addresses;  the  default  is  the  current  line.  The 
resulting  current  line  is  the  last  line  printed.  The  p  command  may  be  appended  to  any  command 
other  than  e,  f,  r,  or  w.  For  example,  dp  deletes  the  current  line  and  prints  the  new  current  line. 

P  Toggle  prompting  on  or  off.  When  prompting  is  in  effect,  the  editor  prompts  with  a  *  for  com¬ 
mands.  A  subsequent  P  command  turns  prompting  off. 

q  Quit.  Exit  from  ed.  Note,  however,  that  the  buffer  is  not  automatically  written  out;  you  must 
write  any  changes  to  be  saved  with  the  w  command;  ed  warns  you  once  if  you  have  not  saved 
your  changes  (unless  the  option  is  in  effect).  A  second  q  forces  ed  to  exit  regardless,  destroy¬ 
ing  the  buffer’s  contents. 
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Q  Force  quit.  This  is  the  same  as  q,  but  you  do  not  get  any  warning  if  you  have  not  previously  writ¬ 
ten  out  the  buffer,  ed  simply  exits. 

r  filename 

Read  in  the  contents  of  filename^  after  the  addressed  line.  If  filename  is  not  given,  the  current 
filename,  if  any,  is  used  (see  the  e  and  f  commands).  The  current  filename  is  not  altered;  if  there 
is  no  current  filename,  filename  becomes  the  current  filename,  r  accepts  one  address ^  the  default 
is  $.  Address  0  is  legal  for  r,  in  which  case  the  file  is  read  in  at  the  beginning  of  the  buffer.  If  the 
read  is  successful,  the  number  of  characters  read  is  typed.  The  resulting  current  line  is  the  last  line 
read  in  from  the  file.  If  filename  is  replaced  by  a  shell  (sh(l))  command  prefaced  with  a  !,  the 
shell  command  is  executed  and  its  output  is  read  in.  Such  a  shell  command  is  not  remembered  as 
the  current  filename. 

siREtrst 

s/REirsIg 

s/REirsIn 

Substitute,  Search  each  addressed  line  for  the  first  occurrence  of  a  string  matching  the  specified 
RE^  and  replace  it  with  rj,  the  replacement  string.  If  g  (global  suffix)  is  appended  to  the  com¬ 
mand,  replace  all  (non-overlapped)  matching  strings  in  each  addressed  line  with  the  replacement 
string  rs.  Note:  the  g  si^fix  is  distinct  from  the  g  command.  If  a  number  n  is  appended,  replace 
only  the  n'th  occurrence  of  the  matched  string  on  each  addressed  line,  s  accepts  one  or  two 
addresses;  the  default  is  the  current  line.  The  resulting  current  line  is  the  last  line  on  which  a  sub¬ 
stitution  is  made.  An  error  results  if  RE  matches  no  strings  in  the  addressed  line  or  range.  Any 
character  (other  than  SPACE  or  NEWLINE  can  be  used  instead  of  /  to  delimit  RE  and  rs.  As  with 
re’s  in  addresses,  you  can  refer  to  the  entire  string  matched  by  RE  with  an  *&’;  you  can  refer  to 
parenthesized  substrings  within  RE  using  \1 , . .  \n.  When  %  is  the  only  character  in  rs,  the  rs  from 
in  the  most  recent  substitute  command  is  used  as  the  current  rs.  The  %  loses  its  special  meaning 
when  it  is  in  a  replacement  string  of  more  than  one  character,  or  if  it  is  preceded  by  a  backslash. 

A  line  may  be  split  by  substituting  a  NEWLINE  character  into  it.  The  NEWLINE  in  the  replace¬ 
ment  must  be  escaped  by  preceding  with  an  ‘\’.  Such  substitutions  cannot  be  done  as  part  of  a  g  or 
V  command  list. 

taddress 

Transfer.  Transpose  a  copy  of  the  addressed  range  of  lines  to  just  after  the  given  address,  t 
(transfer)  is  like  m  (move),  except  that  it  copies  of  the  lines,  rather  than  moving  them,  t  accepts 
two  addresses  preceding  the  operation  letter,  the  current  address  is  the  default.  The  resulting 
current  line  is  the  last  line  copied.  Address  0  is  allowed. 

u  Undo.  Reverse  the  effect  of  the  most  recent  command  that  modified  the  buffer.  A  second  u 
undoes  the  undo  operation. 

\l RE  I  command-list 

This  command  is  the  same  as  the  global  command  g  except  that  the  command-list  is  executed  with 
L’  initially  set  to  every  line  that  does  not  match  the  RE. 

(l.$) 

Similar  to  the  G  command,  except  that  the  lines  selected  are  those  that  do  not  match  the  RE. 
yf filename 

Write  the  addressed  lines  to  filename.  If  the  file  does  not  exist,  ed  creates  it.  The  current  filename 
is  not  altered;  if  there  is  no  current  filename,  then  filename  becomes  current.  If  no  filename  is 
given,  the  current  filename,  if  any,  is  used,  w  accepts  one  or  two  addresses;  the  default  is  all  lines 
in  the  file.  The  current  line  is  unchanged.  If  the  command  is  successful,  the  number  of  characters 
written  is  displayed.  If  filename  is  replaced  by  a  shell  (sh(l))  command  prefaced  with  a  *!’,  the 
shell  command  is  executed  with  standard  input  taken  from  the  addressed  lines.  Such  a  shell  com¬ 
mand  is  not  remembered  as  the  current  filename. 
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(1.^)  ^ filename 

Like  w,  but  append  the  addressed  lines  onto  the  named  file. 

X  Encrypt  the  file,  ed  prompts  for  an  encryption  key  from  the  standard  input  Subsequent  e,  r,  and 
w  commands  encrypt  and  decrypt  the  text  with  this  key  (see  crypt(l)).  An  empty  key  turns  off 
encryption.  Encryption  can  also  be  specified  on  the  command  line  with  the  -x  option. 

($) 

=  Display  the  line  number  of  the  addressed  line;  the  current  line  remains  unchanged. 

\  shell-command 

Run  a  shell  command,  shell-command  is  a  (Bourne  shell)  command  line,  ed  replaces  the  unes¬ 
caped  character  %  with  the  current  filename;  if  a  !  appears  as  the  first  character  of  the  shell  com¬ 
mand,  it  is  replaced  with  the  text  of  the  previous  shell  command.  (!!  repeats  the  last  shell  com¬ 
mand.)  If  any  such  expansion  is  performed,  the  expanded  line  is  echoed.  The  current  line  is 
unchanged. 

address 

NEWLINE 

An  address,  alone  on  a  line,  prints  the  addressed  line.  A  NEWLINE  alone  is  equivalent  to  ‘*+lp’, 
which  is  useful  for  stepping  forward  through  the  buffer. 

If  an  interrupt  signal  (ASCII  DEL  or  BREAK)  is  sent,  ed  prints  a  ?  and  returns  to  its  command  level. 

File  Format  Specification  Support 

ed  supports  the  fspec(5)  formatting  capability  for  displaying  lines.  When  the  first  line  of  a  file  is  a  format 
specification  of  the  form: 

<:ts[fts] . . .  smax:> 

where  ts  is  the  column  number  of  a  TAB  stop  and  max  is  the  maximum  line  length  for  display  purposes,  and 
with  the  terminal  in  ‘stty  -tabs’  or  ‘stty  tab3’  mode  (see  stty(l  V)  for  details),  the  indicated  TAB  stops  are 
used  in  displayed  lines.  While  inserting  text,  however,  TAB  stops  are  set  to  every  eighth  column. 

ENVIRONMENT 

The  environment  variables  LC  CTYPE,  LANG,  and  LC^default  control  the  character  classification 
throughout  ed.  On  entry  to  ed,  these  environment  variables  are  checked  in  the  following  order: 
LC  CTYPE,  LANG,  and  LC  default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC  CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  “C"  locale. 

FILES 

/usr/tmp/e#  temporary;  #  is  the  process  number 

ed.hup  file  for  saved  work  if  the  terminal  is  hung  up 

SEE  ALSO 

crypt(l),  ex(l),  grep(lV),  sed(lV),  sh(l),  stty(lV),  vi(l),  regexp(3),  fspec(5),  locale(5),  iso_8859_l(7) 
Editing  Text  Files 
LIMITATIONS 

The  following  limitations  apply: 

512  characters  per  line. 

256  characters  per  global  command-list. 

1024  characters  per  filename. 

The  limit  on  the  number  of  lines  depends  on  the  amount  of  user  memory: 
each  line  takes  1  word. 

When  reading  a  file,  ed  discards  ASCII  NUL  characters  and  all  characters  after  the  last  NEWLINE.  Files 
(such  as  executable  images)  that  contain  characters  not  in  the  ASCII  set  (bit  8  on)  cannot  be  edited  using  ed. 
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If  a  file  is  not  terminated  by  a  NEWLINE  character,  ed  adds  one  and  prints  a  message  saying  that  it  has  done 
so. 

If  the  closing  delimiter  of  an  RE  or  of  a  replacement  string  (such  as  /)  would  be  the  last  character  before  a 
NEWLINE,  that  delimiter  can  be  omitted,  in  which  case  the  addressed  line  is  printed.  The  following  pairs 
of  commands  are  equivalent: 

s/sl/s2  s/sl/s2/p 
g/sl  g/sl/p 

?sl  ?sl? 

DIAGNOSTICS 

?  For  command  errors. 

7file:error 

For  an  inaccessible  file  (use  the  h  (help)  and  H  (Help)  commands  for  detailed  explanations). 

If  changes  have  been  made  in  the  buffer  since  the  last  w  command,  ed  issues  a  warning  ?  when  a  command 
is  given  that  would  destroy  the  buffers  contents.  A  second  e  or  q  command  at  this  point  will  take  effect. 
The  and  -s  command-line  options  inhibit  this  feature. 

WARNINGS 

A  !  command  cannot  be  subject  to  a  g  or  a  v  command. 

The  sequence  \n  in  an  RE  does  not  match  a  NEWLINE  character. 

Files  encrypted  directly  with  the  crypt(l)  command  with  the  null  key  cannot  be  edited. 

The  encryption  facilities  of  ed  are  not  available  on  software  shipped  outside  the  U.S. 

If  the  editor  input  is  coming  from  a  command  file,  the  editor  exits  at  the  first  failure  of  a  command  in  that 
file. 
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NAME 

eject  “  eject  media  device  from  drive 
SYNOPSIS 

eject  [  -dfnq  ]  [  device  I  nickname  ] 

AVAILABILITY 

This  command  is  not  available  on  Sun  386/  systems. 

DESCRIPTION 

eject  is  used  for  those  removable  media  devices  that  do  not  have  a  manual  eject  button.  The  device  may  be 
specified  by  its  name  or  by  a  nickname;  if  no  device  is  specified  the  default  device  is  used. 

Only  devices  that  support  eject  under  program  control  respond  to  this  command. 

It  is  not  recommended  to  physically  eject  media  from  a  device  which  contains  mounted  filesystems,  eject 
automatically  searches  for  any  mounted  filesystems  which  reside  on  the  device  and  attempts  to  umount 
them  prior  to  ejecting  the  media  (see  mount(8)).  If  the  unmount  operation  fails,  eject  prints  a  warning 
message  and  exits.  The  -f  flag  may  be  used  to  specify  an  eject  even  if  the  device  contains  mounted  parti¬ 
tions. 

eject  can  also  display  its  default  device  and  a  list  of  nicknames. 

OPTIONS 
-d 

-f 
-n 

-q 

device 
nickname 

FILES 

/dev/rfdOc 
/dev/rsrO 
/dev/srO 

SEE  ALSO 

fd(4S),  sr(4S),  inount(8) 

EXIT  STATUS 

eject  returns  the  following  exit  codes: 

0  If  the  operation  was  successful  or,  with  the  -q  option,  the  media  is  in  the  drive, 

1  If  the  operation  was  unsuccessful  or,  with  the  -q  option,  the  media  is  not  in  the  drive. 

2  If  invalid  flags  were  specified. 

3  If  an  ioctl( )  request  failed. 

DIAGNOSTICS 

A  short  help  message  is  printed  if  an  unknown  flag  is  specified.  A  diagnostic  is  printed  if  the  device  name 
cannot  be  opened  or  does  not  support  eject. 

Device  Busy  An  attempt  was  made  to  eject  a  device  that  has  a  mounted  filesystem.  A  warning  message  is 
printed  when  doing  a  forced  eject  of  a  mounted  device. 

BUGS 

There  should  be  a  way  to  change  the  default  on  a  per-user  basis. 


Display  the  name  of  the  default  device  to  be  ejected. 

Force  the  device  to  eject  even  if  it  is  busy. 

Display  the  nickname  to  device  name  translation  table. 

Query  to  see  if  the  media  is  present. 

Specify  which  device  to  eject,  by  the  name  it  appears  in  the  directory  /dev. 
Specify  which  device  to  eject,  by  its  nickname  as  known  to  this  command. 

raw  files 
block  files 
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NAME 

enablenamlock,  disablenumlock  -  enable  or  disable  the  numlock  key 

SYNOPSIS 

enablenumlock 

disablenumlock 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 j:  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

When  you  press  the  **Num  Lock”  key  and  then  press  one  of  the  keys  numbered  R1  through  R 15  on  the 
right  keypad,  the  character  on  the  upper  part  of  tlie  key  is  generated  rather  than  the  key’s  function. 

In  previous  releases,  “Num  Lock”  was  enabled  only  in  DOS  windows  and  in  some  third-party  UNIX  appli¬ 
cations.  Currently,  “Num  Lock”  is  enabled  by  default  for  the  right  keypad  in  all  SunView  windows. 

enablenumlock  re-enables  “Num  Lock”  for  applications  that  expect  it  to  be  enabled. 

SEE  ALSO 

Sun386i  User’s  Guide 

BUGS 

The  default  enabling  of  the  “Num  Lock”  key  is  incompatible  with  some  applications  with  special  work 
around  code  to  enable  the  “Num  Lock”  key.  These  applications  require  the  use  of  disablenumlock.  DOS 
applications  are  not  affected. 
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NAME 

env  -  obtain  or  alter  environment  variables  for  command  execution 
SYNOPSIS 

env  [  -  ]  [  name  rvalue  . . .  ]  [  command  ] 

DESCRIPTION 

env  obtains  the  current  environment,  modifies  it  according  to  its  arguments,  and  executes  the  command 
with  the  modified  environment  that  results. 

If  no  command  is  specified,  the  resulting  environment  is  displayed. 

OPTIONS 

-  Ignore  the  environment  that  would  otherwise  be  inherited  from  the  current  shell. 

Restricts  the  environment  for  command  to  that  specified  by  the  arguments. 

nam€=value  Set  the  environment  variable  filename  to  value  and  add  it  to  the  environment. 

SEE  ALSO 

sh(l),  execve(2V),  profil(2),  environ(5V) 
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NAME 

eqn,  neqn,  checkeq  -  typeset  mathematics 
SYNOPSIS 

eqn  [  -4xy  ]  [  -f/i  ]  [  -pn  ]  [  -sn  ]  [filename  ] . . . 
neqn  [filename  ]  . . . 
checkeq  [filename  ] . . . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

eqn  (and  neqn)  are  language  processors  to  assist  in  describing  equations,  eqn  is  a  preprocessor  for 
troff(l)  and  is  intended  for  devices  that  can  print  troff’s  output  neqn  is  a  preprocessor  for  nroff(l)  and  is 
intended  for  use  with  terminals.  Usage  is  almost  always: 

example%  eqn  filename  ...  |  troff 
example  %  neqn  filename  ...  |  nroff 

If  no  filenames  are  specified,  eqn  and  neqn  read  from  the  standard  input.  A  line  beginning  with  .EQ  marks 
the  start  of  an  equation;  the  end  of  an  equation  is  marked  by  a  line  beginning  with  .EN.  Neither  of  these 
lines  is  altered,  so  they  may  be  defined  in  macro  packages  to  get  centering,  numbering,  etc.  It  is  also  possi¬ 
ble  to  set  two  characters  as  “delimiters”;  subsequent  text  between  delimiters  is  also  treated  as  eqn  input, 

checkeq  reports  missing  or  unbalanced  delimiters  and  .EQ/.EN  pairs. 

Set  equation  delimiters  set  to  characters  x  and  y  with  the  command-line  argument.  The  more  com¬ 
mon  way  to  do  this  is  with  delinuy  between  .EQ  and  .EN.  The  left  and  right  delimiters  may  be 
identical.  Delimiters  are  turned  off  by  delim  off  appearing  in  the  text.  All  text  that  is  neither 
between  delimiters  nor  between  .EQ  and  .EN  is  passed  through  untouched. 

Change  font  to  n  globally  in  the  document.  The  font  can  also  be  changed  globally  in  the  body  of 
the  document  by  using  the  gfont  directive. 

Reduce  subscripts  and  superscripts  by  n  point  sizes  from  the  previous  size.  In  the  absence  of  the 
-p  option,  subscripts  and  superscripts  are  reduced  by  3  point  sizes  from  the  previous  size. 

Change  point  size  to  n  globally  in  the  document.  The  point  size  can  also  be  changed  globally  in 
the  body  of  the  document  by  using  the  gsize  directive. 

EQN  LANGUAGE 

Tokens  within  eqn  are  separated  by  braces,  double  quotes,  tildes,  circumflexes,  SPACE,  TAB,  or  NEWUNE 
characters.  Braces  { )  are  used  for  grouping;  generally  speaking,  anywhere  a  single  character  like  x  could 
appear,  a  complicated  construction  enclosed  in  braces  may  be  used  instead.  Tilde  (~)  represents  a  full 
SPACE  in  the  output,  circumflex  (^)  half  as  much. 

Subscripts  and  superscripts  are  produced  with  the  keywords  sub  and  sup.  Thus  *x  sub  i’  makes  x^  ,  ‘a  sub 
i  sup  2’  produces  and  ‘e  sup  {x  sup  2  +  y  sup  2}’  gives  e*  . 

Fractions  are  made  with  over:  ‘a  over  b’  yields  — . 

b 

sqrt  makes  square  roots:  ‘1  over  sqrt  {ax  sup  2  +bx+c}’  results  in  -p==L= 

The  keywords  from  and  to  introduce  lower  and  upper  limits  on  arbitrary  things 
from  {n~>  inf  }  sum  from  0  to  n  x  sub  i\ 


n 

:  lim  5^/  is  made  with  ‘lim 
n->«0 


OPTIONS 

-dxy 

-in 

~pn 

-sn 
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Left  and  right  brackets,  braces,  etc.,  of  the  right  height  are  made  with  left  and  right:  ‘left  [  x  sup  2  +  y  sup 


2  over  alpha  right  ]  ■'='‘1’  produces 


a 


—  1.  The  right  clause  is  optional.  Legal  characters  after 


left  and  right  are  braces,  brackets,  bars,  c  and  f  for  ceiling  and  floor,  and  "  "  for  nothing  at  all  (useful  for  a 
right*side-only  bracket). 


Vertical  piles  of  things  are  made  with  pile,  Ipile,  cpile,  and  rpile:  ‘pile  {a  above  b  above  c}’  produces  b. 

There  can  be  an  arbitrary  number  of  elements  in  a  pile.  Ipile  left-justifies,  pile  and  cpile  center,  with  dif¬ 
ferent  vertical  spacing,  and  rpile  right  justifies. 

Matrices  are  made  with  matrix:  ‘matrix  {  Icol  {  x  sub  i  above  y  sub  2  }  ccol  {  1  above  2  }  }*  produces 

Xi  1 

2'  addition,  there  is  rcol  for  a  right-justified  column. 

Diacritical  marks  are  made  with  dot,  ^tdot,  hat.  tilde,  bar,  vec,  dyad,  and  under:  ‘x  dot  =  f(t)  bar’  is 
x=f  (0>  ‘y  dotdot  bar  "=“  n  under’  is  y  =  n ,  and  ‘x  vec  y  dyad’  is  j?=  5^. 

Sizes  and  font  can  be  changed  with  size  n  or  size  ±n,  roman,  italic,  bold,  and  font  n.  Size  and  fonts  can 
be  changed  globally  in  a  document  by  gsize  n  and  gfont  n,  or  by  the  command-line  arguments  -sn  and  -fn. 

Successive  display  arguments  can  be  lined  up.  Place  mark  before  the  desired  lineup  point  in  the  first  equa¬ 
tion;  place  lineup  at  the  place  that  is  to  line  up  vertically  in  subsequent  equations. 

Shorthands  may  be  defined  or  existing  keywords  redefined  with  define; 

define  thing  %  replacement  % 

defines  a  new  token  called  thing  which  will  be  replaced  by  replacement  whenever  it  appears  thereafter. 
The  %  may  be  any  character  that  does  not  occur  in  replacement. 

Keywords  like  sum  (j;),  int  (j),  inf  (oo),  and  shorthands  like  >=  (>),  ->  (->),  and  !=  (^)  are  recognized. 
Greek  letters  are  spelled  out  in  the  desired  case,  as  in  alpha  or  GAMMA.  Mathematical  words  like  sin,  cos, 
and  log  are  made  Roman  automatically.  troff(l)  four-character  escapes  like  Xbu  (•)  can  be  used  any¬ 
where.  Strings  enclosed  in  double  quotes  are  passed  through  untouched;  this  permits  keywords  to  be 
entered  as  text,  and  can  be  used  to  communicate  with  troff  when  all  else  fails. 

SEE  ALSO 

tbl(l),  troff(l),  eqnchar(7),  ms(7) 

Formatting  Documents 

BUGS 

To  embolden  digits,  parens,  etc.,  it  is  necessary  to  quote  them,  as  in  ‘bold  "12.3"’. 
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NAME 

error  ~  categorize  compiler  error  messages,  insert  at  responsible  source  file  lines 
SYNOPSIS 

error  [  -n  ]  [  -s  ]  [  -q  ]  [  -v  ]  [  -t  sitffixHst  ]  [  -I  ignorejile  ]  [filename  ] 

DESCRIPTION 

error  analyzes  error  messages  produced  by  a  number  of  compilers  and  language  processors.  It  replaces 
the  painful,  traditional  methods  of  scribbling  abbreviations  of  errors  on  paper,  and  permits  error  messages 
and  source  code  to  be  viewed  simultaneously. 

error  looks  at  error  messages,  either  from  the  specified  file  filename  or  from  the  standard  input,  and: 

•  Determines  which  language  processor  produced  each  error  message. 

•  Determines  the  file  name  and  line  number  of  the  erroneous  line, 

•  Inserts  the  error  message  into  the  source  file  immediately  preceding  the  erroneous  line. 

Error  messages  that  can’t  be  categorized  by  language  processor  or  content  are  not  inserted  into  any  file,  but 
are  sent  to  the  standard  output,  error  touches  source  files  only  after  all  input  has  been  read. 

error  is  intended  to  be  run  with  its  standard  input  connected  with  a  pipe  to  the  error  message  source.  Some 
language  processors  put  error  messages  on  their  standard  error  file;  others  put  their  messages  on  the  stan¬ 
dard  output  Hence,  both  error  sources  should  be  piped  together  into  error.  For  example,  when  using  the 
csh  syntax, 

tutorial  %  make  -s  lint  |  &  error 

will  analyze  all  the  error  messages  produced  by  whatever  programs  make(l)  runs  when  making  lint. 

error  knows  about  the  error  messages  produced  by:  make(l),  cc(lV),  cpp(l),  as(l),  ld(l),  lint(lV),  and 
other  compilers.  For  all  languages  except  Pascal,  error  messages  are  restricted  to  one  line.  Some  error 
messages  refer  to  more  than  one  line  in  more  than  one  file,  in  which  case  error  duplicates  the  error  mes¬ 
sage  and  inserts  it  in  all  the  appropriate  places. 

OPTIONS 

-n  Do  not  touch  any  files;  all  error  messages  are  sent  to  the  standard  output. 

-q  error  asks  whether  the  file  should  be  touched.  A  ‘y’  or  ‘n’  to  the  question  is  necessary  to  continue. 
Absence  of  the  ~q  option  implies  that  all  referenced  files  (except  those  referring  to  discarded  error 
messages)  are  to  be  touched. 

-V  After  all  files  have  been  touched,  overlay  the  visual  editor  vi  with  it  set  up  to  edit  all  files  touched, 
and  positioned  in  the  first  touched  file  at  the  first  error.  If  vi(l)  can’t  be  found,  try  ex(l)  or  ed(l) 
from  standard  pbces. 

-t  suffixlist 

Take  the  following  argument  as  a  suffix  list.  Files  whose  suffices  do  not  appear  in  the  suffix  list  are 
not  touched.  The  suffix  list  is  dot  separated,  and  wildcards  work.  Thus  the  suffix  list: 

.c.y.f*.h 

allows  error  to  touch  files  ending  with  ‘.c’,  ‘.y’,  ‘.f*’  and  *.h’. 

-s  Print  out  statistics  regarding  the  error  categorization. 

error  catches  interrupt  and  terminate  signals,  and  terminates  in  an  orderly  fashion. 

USAGE 

Action  Statements 

error  does  one  of  six  things  with  error  messages. 

synchronize  Some  language  processors  produce  short  errors  describing  which  file  they  are  processing. 

Error  uses  these  to  determine  the  file  name  for  languages  that  don’t  include  the  file  name 
in  each  enor  message.  These  synchronization  messages  are  consumed  entirely  by  error. 
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discard  Error  messages  firom  lint  that  refer  to  one  of  the  two  lint  libraries,  /usr/lib/lint/IUb-lc  and 

/usr/lib/lint/llib-port  are  discarded,  to  prevent  accidentaly  touching  these  libraries. 
Again,  these  error  messages  are  consumed  entirely  by  error. 

nullify  Error  messages  from  lint  can  be  nullified  if  they  refer  to  a  specific  function,  which  is 

known  to  generate  diagnostics  which  are  not  interesting.  Nullified  error  messages  are  not 
inserted  into  the  source  file,  but  are  written  to  the  standard  output.  The  names  of  func¬ 
tions  to  ignore  are  taken  from  either  the  file  named  .errorrc  in  the  user’s  home  directory, 
or  from  the  file  named  by  the  —I  option.  If  the  file  does  not  exist,  no  error  messages  are 
nullified.  If  the  file  does  exist,  there  must  be  one  function  name  per  line. 

not  file  specific  Error  messages  that  can’t  be  intuited  are  grouped  together,  and  written  to  the  standard 
output  before  any  files  are  touched.  They  are  not  inserted  into  any  source  file. 

file  specific  Error  messages  that  refer  to  a  specific  file  but  to  no  specific  line  are  written  to  the  stan¬ 
dard  output  when  that  file  is  touched. 

true  errors  Error  messages  that  can  be  intuited  are  candidates  for  insertion  into  the  file  to  which  they 
refer. 

Only  true  error  messages  are  inserted  into  source  files.  Other  error  messages  are  consumed  entirely  by 
error  or  are  written  to  the  standard  output,  error  inserts  the  error  messages  into  the  source  file  on  the  line 
preceding  the  line  number  in  the  error  message.  Each  error  message  is  turned  into  a  one  line  comment  for 
the  language,  and  is  internally  flagged  with  the  string  ###  at  the  beginning  of  the  error,  and  %% %  at  the 
end  of  the  error.  This  makes  pattern  searching  for  errors  easier  with  an  editor,  and  allows  the  messages  to 
be  easily  removed.  In  addition,  each  error  message  contains  the  source  line  number  for  the  line  the  message 
refers  to.  A  reasonably  formatted  source  program  can  be  recompiled  with  the  error  messages  still  in  it, 
without  having  the  error  messages  themselves  cause  future  errors.  For  poorly  formatted  source  programs 
in  free  format  languages,  such  as  C  or  Pascal,  it  is  possible  to  insert  a  comment  into  another  comment, 
which  can  wreak  havoc  with  a  future  compilation.  To  avoid  this,  format  the  source  program  so  there  are  no 
language  statements  on  the  same  line  as  the  end  of  a  comment. 

FILES 

7.errorrc  function  names  to  ignore  for  lint  error  messages 

/dev/tty  user’s  teletype 

SEE  ALSO 

as(l),  cc(lV),  cpp(l),  csh(l),  ed(I),  ex(l),  Id(l),  lint(IV),  niake(l),  vi(I) 

BUGS 

Opens  the  tty-device  directly  for  user  input. 

Source  files  with  links  make  a  new  copy  of  the  file  with  only  one  link  to  it. 

Changing  a  language  processor’s  error  message  format  may  cause  error  to  not  understand  the  error  mes¬ 
sage. 

error,  since  it  is  purely  mechanical,  will  not  filter  out  subsequent  errors  caused  by  “floodgating”  initiated 
by  one  syntactically  trivial  error.  Humans  are  still  much  better  at  discarding  these  related  errors. 

Pascal  error  messages  belong  after  the  lines  affected,  error  puls  them  before.  The  alignment  of  the  |  mark¬ 
ing  the  point  of  error  is  also  disturbed  by  error. 

error  was  designed  for  work  on  CRT ’s  at  reasonably  high  speed.  It  is  less  pleasant  on  slow  speed  termi¬ 
nals,  and  has  never  been  used  on  hardcopy  terminals. 
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NAME 

ex,  edit,  e  -  line  editor 
SYNOPSIS 

ex  [  -  ]  [  “ILrRsvVxC  ]  [  -t  ]  [  +c  command  I  -c  command  ]  filename. . . 
edit  [  options  ] 

DESCRIPTION 

ex,  a  line  editor,  is  the  root  of  a  family  of  editors  that  includes  edit,  ex(l),  and  vi(l)  (the  display  editor).  In 
most  cases  vi  is  preferred  for  interactive  use. 

OPTIONS 

-  I  -s  Suppress  all  interactive  feedback  to  the  user  (useful  for  processing  ex  scripts  in  shell  files). 

-1  Set  up  for  editing  LISP  programs. 

-L  List  the  names  of  all  files  saved  as  the  result  of  an  editor  or  system  crash. 

-r  Recover  the  indicated  filenames  after  a  system  crash. 

-R  Read  only.  Do  not  overwrite  the  original  file. 

-V  Start  up  in  display  editing  state  using  vi.  You  can  achieve  the  same  effect  by  simply  typing  the 

vi  command  itself. 

-V  Verbose.  Any  non-tty  input  will  be  echoed  on  standard  error.  This  may  be  useful  when  pro¬ 

cessing  editor  commands  within  shell  scripts. 

“X  Prompt  for  a  key  to  be  used  in  encrypting  the  file  being  edited.  When  used  in  conjunction  with 

a  pre-existing  file,  ex  will  make  an  educated  guess  to  determine  whether  or  not  the  input  text 
file  is  already  encrypted. 

-C  Encryption  option;  the  same  as  the  -x  option,  except  that  all  input  text  is  assumed  to  have 

already  been  encrypted.  This  guarantees  decryption  in  the  cases  where  the  -x  option 
incorrectly  determines  that  the  input  file  is  not  already  encrypted  (this  is  extremely  rare,  and 
will  only  occur  in  conjunction  with  the  use  of  files  containing  non-ASCII  text). 

~t  tag  Edit  the  file  containing  the  tag  tag.  A  tags  database  must  first  be  created  using  the  ctags(l) 
command. 

+c  command 

— c  command 

Start  the  editing  session  by  executing  command. 

ENVIRONMENT 

The  editor  recognizes  the  environment  variable  EXINIT  as  a  command  (or  list  of  commands  separated  by  ] 
characters)  to  run  when  it  starts  up.  If  this  variable  is  undefined,  the  editor  checks  for  startup  commands  in 
the  file  $HOME/.exrc  file,  which  you  must  own.  However,  if  there  is  a  .exrc  owned  by  you  in  the  current 
directory,  the  editor  takes  its  startup  commands  from  this  file  —  overriding  both  the  file  in  your  home 
directory  and  the  environment  variable. 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  ex.  On  entry  to  ex,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC  CTYPE,  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSDC.l  “C”  locale. 

FILES 

/usr/lib/ex?.?strings  error  messages 
/usr/lib/ex?.?recover  recover  command 
/usr/lib/ex?.?preserve  preserve  command 
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w 


/■  '  V 

(  ] 


/etc/termcap 

.exrc 

$HOME/.exrc 

/tmp/Exrtrt/irt/i 

/tmp/Rxwnnnn 

/var/preserve 


describes  capabilities  of  terminals 
editor  startup  file  for  current  directory 
user’s  editor  startup  file  if  ./.exrc  is  not  found 
editor  temporary  file 
file  named  buffer  temporary 
preservation  directory 


SEE  ALSO 

awk(l),  ctags(l),  ed(l),  grep(lV),  s€d(lV),  vi(l),  locaIe(5),  termcap(5),  environ(5V),  iso__8859_l(7) 
Editing  Text  Files 

BUGS 

The  z  command  prints  a  number  of  logical  rather  than  physical  lines.  More  than  a  screen  full  of  output 
may  result  if  long  lines  are  present 


File  input/output  errors  do  not  print  a  name  if  the  command  line  *— *  option  is  used. 

There  is  no  easy  way  to  do  a  single  scan  ignoring  case. 

The  editor  does  not  warn  if  text  is  placed  in  named  buffers  and  not  used  before  exiting  the  editor. 

Null  characters  are  discarded  in  input  files,  and  cannot  appear  in  resultant  files. 

With  the  modeline  option  in  effect,  the  editor  checks  the  first  five  lines  of  the  text  file  for  commands  of  the 
form 

ex:  command: 
or 

vi:  command: 

if  any  are  found,  the  editor  executes  them.  This  can  result  in  unexpected  behavior,  and  is  not  recom¬ 
mended  in  any  case.  In  earlier  releases,  modeline  was  in  effect  by  default.  Now  it  is  not,  but  setting  it  in 
the  .exrc  file  or  the  EXEVIT  environment  variable  can  still  produce  untoward  effects. 

RESTRICTIONS 

The  encryption  facilities  of  ex  are  not  available  on  software  shipped  outside  the  U.S. 
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NAME 

expand,  unexpand  -  expand  TAB  characters  to  SPACE  characters,  and  vice  versa 
SYNOPSIS 

expand  [  -tabstop  ]  [  -tabl,tab2,. . tabn  ]  [filename  ...  ] 
unexpand  [ -a  ]  [filename  ...  ] 

DESCRIPTION 

expand  copies  filenames  (or  the  standard  input)  to  the  standard  output,  with  TAB  characters  expanded  to 
SPACE  characters.  BACKSPACE  characters  are  preserved  into  the  output  and  decrement  the  column  count 
for  TAB  calculations,  expand  is  useful  for  pre-processing  character  files  (before  sorting,  looking  at  specific 
columns,  etc.)  that  contain  TAB  characters. 

unexpand  copies  filenames  (or  the  standard  input)  to  the  standard  output,  putting  TAB  characters  back  into 
the  data.  By  default,  only  leading  SPACE  and  TAB  characters  are  converted  to  strings  of  tabs,  but  this  can 
be  overridden  by  the  -a  option  (see  the  OPTIONS  section  below). 

OPTIONS 

expand 

-tabstop 

Specify  ^  a  single  argument,  sets  TAB  characters  tabstop  SPACE  characters  apart  instead  of  the 
default  8. 

-tabl,tab2,. .  ..tabn 

Set  TAB  characters  at  the  columns  specified  by  tab!.. . 

unexpand 

-a  Insert  TAB  characters  when  replacing  a  run  of  two  or  more  SPACE  characters  would  produce  a 
smaller  output  file. 
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NAME 

expr  -  evaluate  arguments  as  a  logical,  arithmetic,  or  string  expression 
SYNOPSIS 

/bin/expr  argument. . . 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/expr  argument. . . 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

expr  evaluates  expressions  as  specified  by  its  arguments.  After  evaluation,  the  result  is  written  on  the  stan¬ 
dard  output  Each  token  of  the  expression  is  a  separate  argument,  so  terms  of  the  expression  must  be 
separated  by  blanks.  Characters  special  to  the  shell  must  be  escaped.  Note:  0  is  returned  to  indicate  a  zero 
value,  rather  than  the  null  string.  Strings  containing  blanks  or  other  special  characters  should  be  quoted. 
Integer-valued  arguments  may  be  preceded  by  a  unary  minus  sign.  Internally,  integers  are  treated  as  32- 
bit,  two’s-complement  numbers. 

The  operators  and  keywords  are  listed  below.  Characters  that  need  to  be  escaped  are  preceded  by  ‘\’.  The 
list  is  in  order  of  increasing  precedence,  with  equal  precedence  operators  grouped  within  {}  symbols. 

expr  \|  expr 

Return  the  first  expr  if  it  is  neither  NULL  nor  0,  otherwise  returns  the  second  expr. 
expr  \&  expr 

Return  the  first  expr  if  neither  expr  is  NULL  or  0,  otherwise  returns  0. 
expr  {  =,N>,  \>=  ,  \<,  \<=,  !=  }  expr 

Return  the  result  of  an  integer  comparison  if  bo,th  arguments  are  integers,  otherwise  returns  the 
result  of  a  lexical  comparison. 

expr  {  +,  -  }  expr 

Addition  or  subtraction  of  integer-valued  arguments. 
expr  { \*,/,  %  )  expr 

Multiplication,  division,  or  remainder  of  the  integer-valued  arguments. 

string  :  regular-expression 
match  string  regular-expression 

The  two  forms  of  the  matching  operator  above  are  synonymous.  The  matching  operators  :  and 
match  compare  the  first  argument  with  the  second  argument  which  must  be  a  regular  expression. 
Regular  expression  syntax  is  the  same  as  that  of  ed(l),  except  that  all  patterns  are  “anchored” 
(treated  as  if  they  begin  with  '')  and,  therefore, "  is  not  a  special  character,  in  that  context.  Nor¬ 
mally,  the  matching  operator  returns  the  number  of  characters  matched  (0  on  failure).  Alterna¬ 
tively,  the  \( . .  .\)  pattern  symbols  can  be  used  to  return  a  portion  of  the  first  argument 

substr  string  integer-1  integer-2 

Extract  the  substring  of  string  starting  at  position  integer- 1  and  of  length  integer -2  characters.  If 
integer- 1  has  a  value  greater  than  the  length  of  string,  expr  returns  a  null  string.  If  you  try  to 
extract  more  characters  than  there  are  in  string,  expr  returns  all  the  remaining  characters  from 
string.  Beware  of  using  negative  values  for  either  integer-1  or  integer-2  as  expr  tends  to  run  for¬ 
ever  in  these  cases. 

index  string  character-list 

Report  the  first  position  in  string  at  which  any  one  of  the  characters  in  character-list  matches  a 
character  in  string. 
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length  string 

Return  the  length  (that  is,  the  number  of  characters)  of  string. 

( expr  )  Parentheses  may  be  used  for  grouping. 

SYSTEM  V  DESCRIPTION 

The  operators  substr,  index,  and  length  are  not  supported. 

EXAMPLES 

1.  a=‘expr  $a  +  V 

Adds  1  to  the  shell  variable  a. 

2.  #  ’For  $a  equal  to  either  "/usr/abc/file"  or  just  "file" ’ 

expr  $a  :  \|  $a 

Returns  the  last  segment  of  a  path  name  (that  is,  the  filename  part).  Watch  out  for  /  alone 
as  an  argument:  expr  will  take  it  as  the  division  operator  (see  BUGS  below). 

3.  #  A  better  representation  of  example  2. 
expr  //$a  :  ’.+A(M)’ 

The  addition  of  the  //  characters  eliminates  any  ambiguity  about  the  division  operator  and 
simplifies  the  whole  expression. 

4.  expr  $VAR  ; 

Returns  the  number  of  characters  in  $VAR. 


SEE  ALSO 

ed(l),  sh(l).  test(lV) 

EXIT  CODE 

expr  returns  the  following  exit  codes: 

0  if  the  expression  is  neither  null  nor  0 

1  if  the  expression  is  null  or  0 

2  for  invalid  expressions. 


DIAGNOSTICS 

syntax  error  for  operator/operand  errors 

non-numeric  argument 

if  arithmetic  is  attempted  on  such  a  string 
division  by  zero  if  an  attempt  to  divide  by  zero  is  made 


BUGS 

After  argument  processing  by  the  shell,  expr  cannot  tell  the  difference  between  an  operator  and  an  operand 
except  by  the  value.  If  $a  is  an  =,  the  command: 

expr  $a  =  ’=’ 

looks  like: 


expr  =  =  = 

as  the  arguments  are  passed  to  expr  (and  they  will  all  be  taken  as  the  =  operator).  The  following  works: 
expr  X$a  =  X= 

Note:  the  match,  substr,  length,  and  index  operators  cannot  themselves  be  used  as  ordinary  strings.  That 
is,  the  expression: 

example  %  expr  index  expur  gator  ious  length 
syntax  error 
example  % 

generates  the  ‘syntax  error’  message  as  shown  instead  of  the  value  1  as  you  might  expect. 
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NAME 

fdformat  ~  format  diskettes  for  use  with  SunOS 

SYNOPSIS 

Sun386i  Systems 

fdformat  [-L]  [-2] 

SPARCstation  1  and  Sun-3/80  Systems 
fdformat  [  -eflv  ]  [  device  ] 

AVAILABLITY 

This  command  is  available  on  Sun386i,  SPARCstation  1  and  Sun-3/80  systems  only. 

DESCRIPTION 

fdformat  is  a  utility  for  formatting  floppy  diskettes.  All  new  blank  diskettes  must  be  formatted  before  they 
can  be  used,  fdformat  formats  and  verifies  each  track  on  the  diskette,  and  terminates  if  it  finds  any  bad 
sectors.  All  existing  data  on  the  diskette,  if  any,  is  destroyed  by  formatting. 

By  default,  fdformat  formats  a  high  density  diskette  with  a  capacity  of  1.44  megabytes.  Use  the  -L  or  -I 
option  to  format  low  density  diskettes  (720K  capacity).  Note:  it  is  not  possible  to  put  a  low  density  format 
onto  a  high  density  floppy  diskette.  High  density  diskettes  can  be  recognized  by  the  high  density  detect 
hole  in  the  lower  right  comer  of  the  diskette,  opposite  the  write  protect  hole  in  the  lower  left  comer. 

The  SPARCstation  1  and  Sun-3/80  version  of  fdformat  writes  a  SunOS  label  on  the  diskette  in  logical  block 
0  after  it  has  been  formatted.  The  label  is  required  on  SPARCstation  1  and  Sun-3/80  systems  if  you  intend 
to  put  a  UNIX  file  system  on  the  floppy  diskette. 

On  Sun386i  systems,  use  the  -2  option  to  format  diskettes  in  the  optional  external  5  1/4"  floppy  drive. 

To  format  a  diskette  for  use  under  MS-DOS,  use  the  MS-DOS  FORMAT  command  in  a  DOS  window  on  the 
Sun386i  system. 

OPTIONS 

Sun386i  Systems 

-L  Format  a  low  density  diskette. 

-2  Format  a  diskette  in  the  optional  external  5.25-inch  floppy  drive. 

SPARCstation  1  and  Sun-3/80  Systems 
-e  Eject  the  diskette  when  done. 

-f  Force.  Do  not  ask  for  confirmation  before  starting  format. 

-1  Format  a  low  density  (720K)  diskette. 

-V  Verify  the  floppy  diskette  after  formatting. 

FILES 

Sun^6i  Systems 

/dev/rfdOc  1.44  megabyte  3.5-inch  high  density  diskette  drive 

/dev/rfdlOc  720  kilobyte  3.5-inch  low  density  diskette  drive 

/dev/rfd2c  High  density  5.25-inch  floppy  drive 

/dev/rfdI2c  Low  density  5.25-inch  floppy  drive 

SPARCstation  1  and  Sun-3/80  Systems 
/dev/rfdOc 

SEE  ALSO 

dos(l),  fd(4S) 
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BUGS 

Currently  bad  sector  mapping  is  not  supported  on  floppy  diskettes.  Therefore,  a  diskette  is  unusable  if 
fdformat  finds  an  error  (bad  sector). 
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NAME 

file  -  determine  the  type  of  a  file  by  examining  its  contents 
SYNOPSIS 

file  [ -fffile  ]  [ -cL  ]  [ -m  mfile ] filename.. . 

DESCRIPTION 

file  performs  a  series  of  tests  on  oach  filename  in  an  attempt  to  determine  what  it  contains.  If  the  contents 
of  a  file  appear  to  be  ASCII  text,  file  examines  the  first  512  bytes  and  tries  to  guess  its  language. 

file  uses  the  file  /etc/magic  to  identify  files  that  have  some  sort  of  magic  number,  that  is,  any  file  containing 
a  numeric  or  string  constant  that  indicates  its  type. 

OPTIONS 

-c  Check  for  format  errors  in  the  magic  number  file.  For  reasons  of  efficiency,  this  validation  is  not 
normally  carried  out.  No  file  type-checking  is  done  under  -c. 

-fffile  Get  a  list  of  filenames  to  identify  from  ffile. 

-L  If  a  file  is  a  symbolic  link,  test  the  file  the  link  references  rather  than  the  link  itself. 

-m  mfile 

Use  mfile  as  the  name  of  an  alternate  magic  number  file. 

EXAMPLE 

This  example  illustrates  the  use  of  file  on  all  the  files  in  a  specific  user’s  directory: 


example  %  pwd 
/usr/blort/misc 
example  %  file  ♦ 

code: 

mc68020  demand  paged  executable 

code.c: 

c  program  text 

counts: 

ascii  text 

doc: 

roff,  nroff ,  or  eqn  input  text 

empty  .file: 

empty 

libz: 

archive  random  library 

memos: 

directory 

project: 

symbolic  link  to  /usr/project 

script: 

executable  shell  script 

titles: 

ascii  text 

s5.stuff: 

example  % 

cpio  archive 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC  default  control  the  character  classification 
throughout  file.  On  entry  to  file,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC^CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  "C”  locale. 

FILES 

/etc/magic 
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SEE  ALSO 

locale(5),  inagic(5) 

BUGS 

file  often  makes  mistakes.  In  particular,  it  often  suggests  that  command  files  are  C  programs. 
Does  not  recognize  Pascal  or  LISP. 
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NAME 

find  -  find  files  by  name,  or  by  other  characteristics 
SYNOPSIS 

find  pathname-list  expression 
find  component 

DESCRIPTION 

find  recursively  descends  the  directory  hierarchy  for  each  pathname  in  the  pathname -list,  seeking  files  that 
match  a  logical  expression  written  using  the  operators  listed  below. 

find  does  not  follow  symbolic  links  to  other  files  or  directories;  it  applies  the  selection  criteria  to  the  sym¬ 
bolic  links  themselves,  as  if  they  were  ordinary  files  (see  !n(lV)  for  a  description  of  symbolic  links). 

If  ihQ  fast-find  feature  is  enabled,  find  displays  pathnames  in  which  a  filename  component  occurs. 

USAGE 

Operators 

In  the  descriptions,  the  argument  n  is  used  as  a  decimal  integer  where  +n  means  more  than  «,  -n  means 
less  than  n,  and  n  means  exactly  n, 

“fstype  type  True  if  the  filesystem  to  which  the  file  belongs  is  of  type  type ,  where  type  is  typically  4.2 
or  nfs. 

filename  True  if  the  filename  argument  matches  the  current  file  name.  Shell  argument  syntax  can 
be  used  if  escaped  (watch  out  for  1,  ?,and  *). 

-perm  onum  True  if  the  file  permission  flags  exactly  match  the  octal  number  onum  (see  chmod(lV)). 

If  onum  is  prefixed  by  a  minus  sign,  more  flag  bits  (017777,  see  chmod(lV))  become 
significant  and  the  flags  are  compared:  (flags &onum)==onum. 

-prune  Always  yields  true.  Has  the  side  effect  of  pruning  the  search  tree  at  the  file.  That  is,  if 

the  current  path  name  is  a  directory,  find  will  not  descend  into  that  directory. 

—type  c  True  if  the  type  of  the  file  is  c ,  where  c  is  one  of: 

b  for  block  special  file  c 

c  for  character  special  file 

d  for  directory 

f  for  plain  file 

p  for  named  pipe  (FIFO) 

1  for  symbolic  link 

s  for  socket 

-links  n  True  if  the  file  has  n  links. 

-user  uname  True  if  the  file  belongs  to  the  user  uname.  If  uname  is  numeric  and  does  not  appear  as  a 

login  name  in  the  /etc/passwd  database,  it  is  taken  as  a  user  ID. 

-nouser  True  if  the  file  belongs  to  a  user  not  in  the  /etc/passwd  database. 

-group  gname  True  if  the  file  belongs  to  group  gnome.  If  gnome  is  numeric  and  does  not  appear  as  a 

login  name  in  the  /etc/group  database,  it  is  taken  as  a  group  ID. 

-nogroup  True  if  the  file  belongs  to  a  group  not  in  the  /etc/group  database. 

-size  n  True  if  the  file  is  n  blocks  long  (512  bytes  per  block).  If  n  is  followed  by  a  c,  the  size  is 

in  characters. 

-inum  n  True  if  the  file  has  inode  number  n . 

-atime  n  True  if  the  file  has  been  accessed  in  n  days. 

Note:  the  access  time  of  directories  in  path-name-list  is  changed  by  find  itself. 

-mtime  n  True  if  the  file  has  been  modified  in  n  days. 
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-ctime  n  True  if  the  file  has  been  changed  in  n  days.  “Changed’*  means  either  that  the  file  has 

been  modified  or  some  attribute  of  the  file  (its  owner,  its  group,  the  number  of  links  to  it, 
etc.)  has  been  changed. 

"-exec  command  True  if  the  executed  command  returns  a  zero  value  as  exit  status.  The  end  of  command 
must  be  punctuated  by  an  escaped  semicolon.  A  command  argument  {}  is  replaced  by 
the  current  pathname. 

-ok  command  Like  -exec  except  that  the  generated  command  is  written  on  the  standard  output,  then 
the  standard  input  is  read  and  the  command  executed  only  upon  response  y. 

-print  Always  true;  the  current  pathname  is  printed. 

-Is  Always  true;  prints  current  pathname  together  with  its  associated  statistics.  These 

include  (respectively)  inode  number,  size  in  kilobytes  (1024  bytes),  protection  mode, 
number  of  hard  links,  user,  group,  size  in  bytes,  and  modification  time.  If  the  file  is  a 
special  file  the  size  field  will  instead  contain  the  major  and  minor  device  numbers.  If  the 
file  is  a  symbolic  link  the  pathname  of  the  linked-to  file  is  printed  preceded  by  The 
format  is  identical  to  that  of  Is  -gilds  (see  ls(I  V)). 

Note:  formatting  is  done  internally,  without  executing  the  Is  program. 

-cpio  device  Always  true;  write  the  current  file  on  device  in  cpio(5)  format  (5120-byte  records). 

-ncpio  device  Always  true;  write  the  current  file  on  device  in  cpio  -c  format  (5120-byte  records). 

-newer  file  True  if  the  current  file  has  been  modified  more  recently  than  the  argument  filename . 

-xdev  Always  true;  find  does  not  traverse  down  into  a  file  system  different  from  the  one  on 

which  current  argument  pathname  resides. 

—depth  Always  true;  find  descends  the  directory  hierarchy,  acting  on  the  entries  in  a  directory 

before  acting  on  the  directory  itself.  This  can  be  useful  when  find  is  used  with  cpio(l) 
to  transfer  files  that  are  contained  in  directories  without  write  permission. 

(expression)  True  if  the  parenthesized  expression  is  true. 

Note:  Parentheses  are  special  to  the  shell  and  must  be  escaped. 

Iprimary  True  if  the  primary  is  false  (!  is  the  unary  not  operator). 

primary  1  [  -a  ]  primary2 

True  if  both  primary  1  and  primary!  are  true.  The  -a  is  not  required.  It  is  implied  by 
the  juxtaposition  of  two  primaries. 

primary  1  -o  primary! 

True  if  either  primary  I  or  primary!  is  true  (-o  is  the  or  operator). 

Fast-Find 

The  fast-find  feature  is  enabled  by  the  presence  of  the  find.codes  database  in  /usrAib/find.  You  must  be 
root  to  build  or  update  this  database  by  running  the  updatedb  script  in  that  same  directory.  You  may  wish 
to  modify  the  updatedb  script  to  suit  your  needs. 

An  alternate  database  can  be  specified  by  setting  the  FCODES  environment  variable. 

EXAMPLE 

In  our  local  development  system,  we  keep  a  file  called  TIMESTAMP  in  all  the  manual  page  directories. 
Here  is  how  to  find  all  entries  that  have  been  updated  since  TIMESTAMP  was  created: 

example  %  find  /usr/share/man/man2  -newer  /usr/share/man/man2/TIMESTAMP  -print 

/usr/share/man/man2 

/usr/share/man/man2/socket.2 

/usr/share/nian/man2/mmap.2 

example% 
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To  find  all  the  files  called  intro.ms  starting  from  the  current  directory: 

example%  find  .  -name  intro.ms  -print 
.  /manuals/assembler/intro.ms 
.  /manuals/sun.core/intro.ms 
.  /manuals/dr  iver.tut/intro.ms 
./manuals/sys.manager/uucp.impl/intro.ms 
./supplements/general.works/unix.introduction/intro.ms 
./supplements/programming.tools/sccs/intro.ms 
example  % 

To  recursively  print  all  files  names  in  the  current  directory  and  below,  but  skipping  SCCS  directories: 

example  %  find .  -name  SCCS  -prune  -o  -print 
example  % 

To  recursively  print  all  files  names  in  the  current  directory  and  below,  skipping  the  contents  of  SCCS  direc¬ 
tories,  but  printing  out  the  SCCS  directory  name: 

example  %  find .  -print  -name  SCCS  -prune 
example  % 

To  remove  files  beneath  your  home  directory  named  a.out  or  *.o  that  have  not  been  accessed  for  a  week 
and  that  are  not  mounted  using  NFS: 


example  %  cd 

example%  find .  \(  -name  a.out  -o  -name  ’*.o’  \)  -atime  +7  -exec  rm  {  }  \;  -o  -fstype  nfs  -prune 


FILES 


/usr/lib/find/find.codes 

/usr/lib/find/updatedb 

/usr/lib/find/code 

/usr/lib/find/bigram 

ENVIRONMENT 

FCODES 


database  for  fast  find 

script  to  update  fast-find  database 

fast-find  database  utilities 


alternate  database  for  fast  find 


SEE  ALSO 

chmod(lV),  cpio(l),  In(lV),  Is(lV).  sh(l),  test(lV),  cpio(5),  fs(5) 
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NAME 

finger  -  display  information  about  users 
SYNOPSIS 

finger  [  options  ]  name. . . 

DESCRIPTION 

By  default,  finger  displays  information  about  each  logged-in  user,  including  his  or  her:  login  name,  full 
name,  terminal  name  (prepended  with  a  if  write-permission  is  denied),  idle  time,  login  time,  and  loca¬ 
tion  (comment  field  in  /etc/ttytab  for  users  logged  in  locally,  hostname  for  users  logged  in  remotely)  if 
known. 


Idle  time  is  minutes  if  it  is  a  single  integer,  hours  and  minutes  if  a  ’  is  present,  or  days  and  hours  if  a  d  is 
present. 

When  one  or  more  name  arguments  are  given,  more  detailed  information  is  given  for  each  name  specified, 
whether  they  are  logged  in  or  not.  A  name  may  be  a  first  or  last  name,  or  an  account  name.  Information  is 
presented  in  a  multi-line  format,  and  includes,  in  addition  to  the  information  mentioned  above: 
the  user’s  home  directory  and  login  shell 

the  time  they  logged  in  if  they  are  currently  logged  in,  or  the  time  they  last  logged  in  if  they  are 
not,  as  well  as  the  terminal  or  host  from  which  they  logged  in  and,  if  a  terminal,  the  comment  field 
in  /etc/ttytab  for  that  terminal 

the  last  time  they  received  mail,  and  the  last  time  they  read  their  mail 
any  plan  contained  in  the  file  .plan  in  the  user’s  home  directory 

and  any  project  on  which  they  are  working  described  in  the  file  .project  (also  in  that  directory) 

If  a  name  argument  contains  an  at-sign,  *@’,  then  a  connection  is  attempted  to  the  machine  named  after  the 
at-sign,  and  the  remote  finger  daemon  is  queried.  The  data  returned  by  that  daemon  is  printed.  If  a  long 
format  printout  is  to  be  produced,  finger  passes  the  -I  option  to  the  remote  finger  daemon  over  the  network 
using  the  /W  feature  of  the  protocol  (see  NAMEIFINGER  Protocol). 

OPTIONS 

-m  Match  arguments  only  on  user  name  (not  first  or  last  name). 

-1  Force  long  output  format. 

-s  Force  short  output  format. 

-q  Force  quick  output  format,  which  is  similar  to  short  format  except  that  only  the  login  name,  termi¬ 
nal,  and  login  time  are  printed. 

-i  Force  “idle”  output  format,  which  is  similar  to  short  format  except  that  only  the  login  name,  ter¬ 
minal,  login  time,  and  idle  time  are  printed. 

”b  Suppress  printing  the  user’s  home  directory  and  shell  in  a  long  format  printout. 

-f  Suppress  printing  the  header  that  is  normally  printed  in  a  non-long  format  printout. 

-w  Suppress  printing  the  full  name  in  a  short  format  printout. 

-h  Suppress  printing  of  the  .project  file  in  a  long  format  printout 

-p  Suppress  printing  of  the  .plan  file  in  a  long  format  printout 

FILES 

/etc/utmp 
/etc/passwd 
/var/adm/lastlog 
/etc/ttytab 
'/.plan 
'/.project 


who  is  logged  in 
for  users’  names 
last  login  times 
terminal  locations 
plans 
projects 
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SEE  ALSO 

passwd(l),  w(l),  who(l),  whois(l) 

Harrenstien,  K.,  NAMEIFINGER  Protocol,  1977  December  30,  RFC  742. 

BUGS 

Only  the  first  line  of  the  .project  file  is  printed. 
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NAME 

fmt,  fmt_mail  -  simple  text  and  mail-message  formatters 
SYNOPSIS 

fmt  [  -cs  ]  [  -width  ]  [  inputfile. , .  ] 
fmt_mail  [  -cs  ]  [  -width  ]  [  inputfile  . . .  ] 

DESCRIPTION 

fmt  is  a  simple  text  formatter  that  fills  and  joins  lines  to  produce  output  lines  of  (up  to)  the  number  of  char¬ 
acters  specified  in  the  -width  option.  The  default  width  is  72.  fmt  concatenates  the  inputfile  s  listed  as 
arguments.  If  none  are  given,  fmt  formats  text  from  the  standard  input. 

Blank  lines  are  preserved  in  the  output,  as  is  the  spacing  between  words,  fmt  does  not  fill  lines  beginning 
with  for  compatibility  with  nroff(l).  Nor  does  it  fill  lines  starting  with  ‘From:’  (but  for  full  compatibil¬ 
ity  with  mail(l),  use  fmt_mail). 

Indentation  is  preserved  in  the  output,  and  input  lines  with  differing  indentation  are  not  joined  (unless  -c  is 
used). 

fmt  can  also  be  used  as  an  in-line  text  filter  for  vi(l);  the  vi  command: 

!}ftnt 

reformats  the  text  between  the  cursor  location  and  the  end  of  the  paragraph. 

fmt_mail  is  a  script  that  formats  and  sends  mail  messages.  It  leaves  mail  header  lines  untouched,  and  runs 
the  remainder  of  the  message  through  fmt  -s.  The  resulting  message  is  passed  along  to  sendmail(8),  which 
routes  it  to  the  recipient. 

OPTIONS 
-C 


-s 

-width 
ENVIRONMENT 

The  environment  variables  LC__CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  fmt.  On  entry  to  fmt,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC__default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.I  “C”  locale. 

SEE  ALSO 

mail(l),  nroff(l),  vi(l) 


Crown  margin  mode.  Preserve  the  indentation  of  the  first  two  lines  within  a  paragraph,  and  align 
the  left  margin  of  each  subsequent  line  with  that  of  the  second  line.  This  is  useful  for  tagged  para¬ 
graphs. 

Split  lines  only.  Do  not  join  short  lines  to  form  longer  ones.  This  prevents  sample  lines  of  code, 
and  other  such  “formatted”  text,  from  being  unduly  combined. 

Fill  output  lines  to  up  to  width  columns. 
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NAME 

fold  -  fold  long  lines  for  display  on  an  output  device  of  a  given  width 

SYNOPSIS 

fold  [-width]  [me] 

DESCRIPTION 

Fold  the  contents  of  the  specified  files,  or  the  standard  input  if  no  files  are  specified,  breaking  the  lines  to 
have  maximum  width  width.  The  default  for  width  is  80.  Width  should  be  a  multiple  of  8  if  tabs  are 
present,  or  the  tabs  should  be  expanded  using  expand(l)  before  using  fold. 

SEE  ALSO 

expand(l) 

BUGS 

Folding  may  not  work  correctly  if  underlining  is  present. 
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NAME 

fontedit  -  a  vfont  screen-font  editor 
SYNOPSIS 

fontedit  [  generic-tool-argument  ] . . .  {fontjiame  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  information  on  how  to  install  optional  software, 

DESCRIPTION 

fontedit  is  an  editor  for  fixed-width  fonts  in  vfont  format  whose  characters  are  no  taller  than  24  pixels 
(larger  characters  will  not  fit  completely  onto  the  screen).  For  a  description  of  vfont  format,  see  vfont(5). 

OPTIONS 

generic-tool-argument  « 

fontedit  accepts  any  generic  tool  argument  as  described  in  sunview(l).  Otherwise,  you  can  mani¬ 
pulate  the  tool  using  the  Frame  Menu. 

COMMANDS 

To  edit  a  font,  type  ‘fontedit’.  A  fontjiame  may  be  supplied  on  the  command  line  or  may  be  typed  into 
the  Control  panel  once  the  program  has  started.  If  it  exists,  the  fontjiame  file  must  be  in  vfont  format. 
When  the  program  starts,  it  displays  a  single  large  window  containing  four  subwindows.  From  top  to  bot¬ 
tom,  the  four  subwindows  are: 

1)  The  top  subwindow,  a  message  subwindow,  displays  messages,  prompts,  and  warnings. 

2)  The  second  subwindow  from  the  top,  an  Control  panel,  allows  you  to  set  global  parameters  for  the 
entire  font  and  specify  operations  for  editing  any  single  character.  The  options  are: 

(Load)  Load  in  the  font  specified  in  the  file  name  field.  The  program  will  warn  you  if  you  try  to 
read  over  a  modified  font. 

(Store)  Store  the  current  font  onto  disk  with  the  name  in  file  name  field. 

(Quit)  Quit  the  program;  warns  you  if  you  have  modified  the  font. 

Font  name: 

The  name  of  the  font. 

Max  Width  and  Max  Height: 

The  size,  in  pixels,  of  the  largest  character  in  the  font.  If  you  edit  an  existing  font,  these 
parameters  are  set  automatically;  you  must  set  them  if  you  are  creating  a  new  font. 
Changing  either  of  these  values  for  an  existing  font  may  alter  the  glyph  of  some  charac¬ 
ters  of  the  font.  If  the  glyph  size  of  a  character  is  larger  than  the  new  max  size,  then  that 
character  is  clipped  to  the  new  size  (its  bottom  and  right  edges  are  moved  in).  However,  if 
a  glyph’s  size  is  smaller  than  the  new  size,  the  glyph  is  left  alone. 

Caps  Height  and  X-Height: 

The  distance,  in  pixels,  between  the  top  of  a  capital  and  lowercase  letter  and  the  baseline. 
When  an  existing  font  is  edited,  the  values  of  Caps  Height  and  X-Height  are  estimated 
hy  fontedit,  and  may  require  some  adjustment. 

Baseline:  The  number  of  pixels  from  the  top  (that  is,  the  upper  left  comer)  of  the  character  to  the 
baseline.  For  an  existing  font,  the  value  of  the  largest  baseline  distance  is  used.  For  a  new 
font,  each  character  will  have  the  same  baseline  distance.  If  this  value  is  changed,  then 
the  baseline  distance  for  all  characters  in  the  font  will  be  the  new  value. 

(Apply)  Apply  the  cuirent  values  of  Max  Width,  Max  Height,  Caps  Height,  X-Height,  and 
Baseline  to  the  font.  That  is,  changes  made  to  these  values  do  not  take  effect  until  Apply 
is  selected. 
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Operation: 

This  is  a  list  of  drawing  and  editing  operations  that  you  can  perform  on  a  character.  For 

drawing,  the  left  mouse  button  draws  in  black,  and  the  middle  draws  in  white.  Operations 

are: 

Single  Pt  Press  a  mouse  button  down  and  a  grey  cell  will  appear;  move  the  mouse  and 
the  cell  will  follow  it.  Releasing  the  button  will  draw. 

Pt  Wipe  Pressing  a  button  down  will  draw  and  moving  with  the  button  down  will  con¬ 
tinue  drawing  until  the  button  is  released. 

Line  Button  down  marks  the  end  point  of  a  line;  moving  with  the  button  down 
rubber  bands  a  line;  releasing  button  draws  the  line. 

Rect  Like  Line  except  draws  a  rectangle. 

Cut  Button  down  marks  one  end  of  rectangle,  and  moving  rubber  bands  the  out¬ 

line  of  the  rectangle.  Button  up  places  the  contents  of  the  rectangle  into  a 
buffer  and  then  “cuts”  (draws  in  white)  the  rectangular  region  from  the 
character.  The  Paste  operation  (below)  gets  the  data  from  the  buffer. 

Copy  Like  Cut  except  that  the  region  is  just  copied;  no  change  is  made  to  the  char¬ 
acter. 

Paste  Button  down  displays  a  rectangle  the  size  of  the  region  in  the  buffer.  Moving 
with  the  button  down  moves  the  rectangle.  Button  up  pastes  the  contents  of 
the  buffer  into  the  character. 

The  contents  of  the  paste  buffer  cannot  be  transferred  between  tools. 

In  Copy  or  Cut  mode,  holding  down  the  shift  key  while  pressing  the  left  or 
middle  mouse  button  will  perform  a  Paste  action.  For  best  results,  after  plac¬ 
ing  a  region  in  the  buffer,  press  down  the  shift  key  and  hold  it  down,  then 
press  down  the  mouse  button.  Release  the  mouse  key  to  paste  the  region  and 
then  release  the  shift  key. 

3)  The  third  subwindow  echoes  the  characters  in  the  current  font  as  they  are  typed.  Note  that  the  cursor 
must  be  in  this  window  in  order  to  see  the  characters.  Your  character  delete  key  will  delete  the  echoed 
characters. 

4)  The  bottom  subwindow,  the  editing  subwindow,  displays  eight  smaller  squares  at  its  top;  these  are 
called  edit  buttons.  The  top  section  of  each  of  these  buttons  contains  a  line  of  text  in  the  form  nnn:  c, 
where  nnn  is  the  hexadecimal  number  of  the  character  and  c  is  the  standard  ASCII  character 
corresponding  to  that  number.  In  the  lower  section  of  the  button  the  character  of  the  current  font,  if  it 
exists,  is  displayed.  Clicking  once  over  an  editing  button  selects  its  character  for  editing. 

Just  below  this  row  of  buttons  is  a  box  with  the  characters  “0  9  A  Z  a  z”  in  it.  This  box  is  called  a 
slider.  The  slider  allows  you  to  scroll  around  in  the  font  and  select  which  section  of  the  font  you  want 
displayed  in  the  edit  buttons.  The  black  rectangle  near  “a”  is  an  indicator  which  shows  the  section 
of  the  font  that  is  displayed  in  the  buttons  above.  To  move  the  indicator,  select  it  by  pressing  the  left 
or  middle  mouse  button  down  over  the  indicator  and  then  move  the  mouse  to  the  left  or  right  with  the 
button  down;  the  indicator  will  slide  along  with  the  cursor.  Releasing  the  button  selects  the  new  sec¬ 
tion  of  the  font.  A  faster  method  of  moving  about  in  the  font  is  to  just  press  down  and  release  the 
mouse  button  above  the  area  you  want  without  bothering  to  drag  the  indicator.  Another  method  of 
scrolling  through  the  characters  of  the  font  is  to  press  a  key  on  the  keyboard  when  the  cursor  is  in  the 
bottom  window;  that  character  is  the  first  one  displayed  in  the  edit  buttons. 

EDITING  CHARACTERS: 

To  edit  a  character,  click  once  over  the  edit  button  where  the  character  is  displayed.  When  you  do  this,  an 

edit  pad  will  appear  in  the  bottom  subwindow. 
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The  edit  pad  consists  of  an  editing  area  bordered  by  scales,  a  proof  area,  and  3  command  buttons.  The  edit¬ 
ing  area  is  Max  Width  by  Max  Height  when  the  pad  opens,  and  displays  a  magnified  view  of  the  selected 
character.  Black  squares  indicate  foreground  pixels.  The  editing  area  is  surrounded  by  scales  which  show 
the  current  Caps  Height,  X-Height  and  Baseline  in  reverse  video. 

Just  outside  the  scales,  on  the  top,  right  side,  and  bottom  of  the  pad,  are  three  small  boxes  with  the  capital 
letters  "R",  "B",  and  "A"  in  them.  These  boxes  are  movable  sliders  that  change  the  right  edge,  bottom 
edge,  and  x-axis  advance  of  the  character  respectively.  In  a  fixed-width  font,  these  values  are  usually  the 
same  for  all  characters;  however,  in  a  variable-width  font  these  controls  can  be  used  to  set  these  properties 
for  each  character. 

To  the  right  of  the  pad  is  the  proof  area  where  the  character  is  displayed  at  normal  (that  is,  screen)  resolu¬ 
tion  and  three  buttons.  The  three  buttons  are: 

Undo  Clicking  the  left  or  middle  mouse  button  undoes  the  last  operation. 

Store  Stores  the  current  representation  of  the  character  in  the  font. 

Quit  Closes  the  edit  pad. 

In  the  bottom  subwindow,  the  right  mouse  button  displays  a  menu  of  operations.  These  operations  are  the 
same  as  those  in  the  control  panel  discussed  above;  you  can  select  the  current  operation  by  either  picking 
the  operation  in  the  control  panel  or  by  selecting  the  appropriate  menu  with  the  right  button  of  the  mouse. 
When  the  cursor  is  in  the  other  subwindows,  the  right  button  displays  the  standard  tool  menu. 

ENVIRONMENT 

The  environment  variables  LC^CTYPE,  LANG,  and  LC_defauIt  control  the  character  classification 
throughout  fontedit.  On  entry  to  fontedit,  these  environment  variables  are  checked  in  the  following  order: 
LC  CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSDC.l  “C”  locale. 

FILES 

/usr/lib/fonts/fixedwidthfonts 

Sun-supplied  screen  fonts 

SEE  ALSO 

sunview(l),  vswap(l),  Iocale(5),  vfont(5),  iso_8859_l(7) 

BUGS 

Results  are  unpredictable  with  variable-width  fonts.  The  baseline  should  be  greater  than  0  or  else  the  font 
cannot  be  read  in  by  fontedit  or  by  sunview(l). 
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NAME 

foption  -  determine  available  floating-point  code  generation  options 

SYNOPSIS 

foption  [  -itype  ] 

AVAILABILITY 

This  command  is  not  available  for  the  Sun386i. 

DESCRIPTION 

foption  has  two  uses.  Called  without  an  argument,  it  sends  a  string  to  standard  output  which  is  the  com¬ 
piler  floating-point  option  corresponding  to  the  type  of  floating-point  hardware  that  would  be  used  by  a 
program  compiled  with  -fswitch.  Exit  stams  is  undefined.  This  usage  is  intended  for  interactively  deter¬ 
mining  available  floating-point  hardware.  On  systems  without  floating-point  hardware,  the  result  would  be 

example  %  foption 
soft 

corresponding  to  the  compiler  option  -fsoft. 

Called  with  an  argument  which  is  one  of  the  compiler  floating-point  options  -ffpa,  -f68881,  -fsoft,  or 
-fswitch,  it  produces  no  output  but  returns  exit  status  0  (true)  if  a  program  compiled  with  that  option  could 
execute  on  this  machine,  and  status  1  (false)  otherwise.  Thus  foption  -fsoft  and  foption  -fswitch  always 
produce  exit  status  0.  This  usage  is  intended  for  shell  scripts  and  Makefiles  that,  for  instance,  select  dif¬ 
ferent  executable  files  or  link  with  different  libraries  according  to  the  floating-point  hardware  present. 

foption  is  undefined  on  Sun-4  systems  since  there  are  no  floating-point  code  generation  options. 

OPTIONS 

-ftype  Return  exit  status  0  if  a  program  compiled  -{type  could  execute  on  this  machme. 

SEE  ALSO 

cc(lV),  fpaversion(8),  mc68881version(8) 
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NAME 

from  “  display  the  sender  and  date  of  newly-arrived  mail  messages 
SYNOPSIS 

from  [  -s  sender  ]  [  username  ] 

DESCRIPTION 

from  prints  out  the  mail  header  lines  in  your  mailbox  file  to  show  you  who  your  mail  is  from.  If  username 
is  specified,  then  username ’s  mailbox  is  examined  instead  of  your  own. 

OPTIONS 

“S  sender  Only  display  headers  for  mail  sent  by  sender. 

FILES 

/var/spool/mail/* 

SEE  ALSO 

biff(l),  mail(l),  old-prmail(l) 
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NAME 

ftp  -  file  transfer  program 
SYNOPSIS 

ftp  [  -dgintv  ]  [  hostname  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

ftp  is  the  user  interface  to  the  ARPANET  standard  File  Transfer  Protocol  (FTP),  ftp  transfers  files  to  and 
from  a  remote  network  site. 

The  client  host  with  which  ftp  is  to  communicate  may  be  specified  on  the  command  line.  If  this  is  done, 
ftp  immediately  attempts  to  establish  a  connection  to  an  FTP  server  on  that  host;  otherwise,  ftp  enters  its 
command  interpreter  and  awaits  instructions  from  the  user.  When  ftp  is  awaiting  commands  from  the  user, 
it  displays  the  prompt  ‘ftp>’. 

OPTIONS 

Options  may  be  specified  at  the  command  line,  or  to  the  command  interpreter. 

-d  Enable  debugging. 

-g  Disable  filename  “globbing.” 

-i  Turn  off  interactive  prompting  during  multiple  file  transfers. 

-n  Do  not  attempt  “auto-login”  upon  initial  connection.  If  auto-login  is  enabled,  ftp  checks  the 
.netrc  file  in  the  user’s  home  directory  for  an  enuy  describing  an  account  on  the  remote  machine. 
If  no  entry  exists,  ftp  will  prompt  for  the  login  name  of  the  account  on  the  remote  machine  (the 
default  is  the  login  name  on  the  local  machine),  and,  if  necessary,  prompts  for  a  password  and  an 
account  with  which  to  login. 

-t  Enable  packet  tracing  (unimplemented). 

-V  Show  all  responses  from  the  remote  server,  as  well  as  report  on  data  transfer  statistics.  This  is 
turned  on  by  default  if  ftp  is  running  interactively  with  its  input  coming  from  the  user’s  terminal. 

COMMANDS 

!  [  command  ] 

Run  command  ^  a  shell  command  on  the  local  machine.  If  no  command  is  given,  invoke  an 
interactive  shell. 

$  macro-name  [  args  ] 

Execute  the  macro  macro-name  that  was  defined  with  the  macdef  command.  Arguments  are 
passed  to  the  macro  unglobbed. 

account  [  passwd  ] 

Supply  a  supplemental  password  required  by  a  remote  system  for  access  to  resources  once  a  login 
has  been  successfully  completed.  If  no  argument  is  included,  the  user  will  be  prompted  for  an 
account  password  in  a  non-echoing  input  mode. 

append  local-file  [  remote-file  ] 

Append  a  local  file  to  a  file  on  the  remote  machine.  If  remote-file  is  left  unspecified,  the  local  file 
name  is  used  in  naming  the  remote  file  after  being  altered  by  any  ntrans  or  nmap  setting.  File 
transfer  uses  the  current  settings  for  “representation  type”,  “file  structure”,  and  “transfer  mode”. 

ascii  Set  the  “representation  type”  to  “network  ASCII”.  This  is  the  default  type. 

bell  Sound  a  bell  after  each  file  transfer  command  is  completed. 

binary  Set  the  “representation  type”  to  “image”. 
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bye  Terminate  the  FTP  session  with  the  remote  server  and  exit  ftp.  An  EOF  will  also  terminate  the  ses¬ 
sion  and  exit. 

case  Toggle  remote  computer  file  name  case  mapping  during  mget  commands.  When  case  is  on 
(default  is  off),  remote  computer  file  names  with  all  letters  in  upper  case  are  written  in  the  local 
directory  with  the  letters  mapped  to  lower  case. 

cd  remote-directory 

Change  the  working  directory  on  the  remote  machine  to  remote-directory. 

cdup  Change  the  remote  machine  working  directory  to  the  parent  of  the  current  remote  machine  work¬ 
ing  directory. 

close  Terminate  the  FTP  session  with  the  remote  server,  and  return  to  the  command  interpreter.  Any 
defined  macros  are  erased. 

cr  Toggle  RETURN  stripping  during  “network  ASCII”  type  file  retrieval.  Records  are  denoted  by  a 
RETURN/LINEFEED  sequence  during  “network  ASCII”  type  file  transfer.  When  cr  is  on  (the 
default),  RETURN  characters  are  stripped  from  this  sequence  to  conform  with  the  UNIX  system 
single  LINEFEED  record  delimiter.  Records  on  non-UNDC-system  remote  hosts  may  contain  single 
LINEFEED  characters;  when  an  “network  ASCII”  type  transfer  is  made,  these  LINEFEED  charac¬ 
ters  may  be  distinguished  from  a  record  delimiter  only  when  cr  is  off. 

delete  remote-file 

Delete  the  file  remote-file  on  the  remote  machine, 
debug  [  debug-value  ] 

Toggle  debugging  mode.  If  an  optional  debug-value  is  specified  it  is  used  to  set  the  debugging 
level.  When  debugging  is  on,  ftp  prints  each  command  sent  to  the  remote  machine,  preceded  by 
the  string 

dir  [  remote-directory  ]  [  local-file  ] 

Print  a  listing  of  the  directory  contents  in  the  directory,  remote-directory^  and,  optionally,  placing 
the  output  in  local-file.  If  no  directory  is  specified,  the  current  working  directory  on  the  remote 
machine  is  used.  If  no  local  file  is  specified,  or  local-file  is  output  is  sent  to  the  terminal. 

disconnect 

A  synonym  for  close. 

form  [format-name  ] 

Set  the  carriage  control  format  subtype  of  the  “representation  type”  \o  format-name .  The  only 
valid  format-name  is  non-print,  which  corresponds  to  the  default  “non-print”  subtype. 

get  remote-file  [  local-file  ] 

Retrieve  the  remote-file  and  store  it  on  the  local  machine.  If  the  local  file  name  is  not  specified,  it 
is  given  the  same  name  it  has  on  the  remote  machine,  subject  to  alteration  by  the  current  case, 
ntrans,  and  nmap  settings.  The  current  settings  for  “representation  type”,  “file  structure”,  and 
“transfer  mode”  are  used  while  transferring  the  file. 

glob  Toggle  filename  expansion,  or  “globbing”,  for  mdelete,  mget  and  mput.  If  globbing  is  turned 
off,  filenames  are  taken  literally. 

Globbing  for  mput  is  done  as  in  csh(i).  For  mdelete  and  mget,  each  remote  file  name  is 
expanded  separately  on  the  remote  machine,  and  the  lists  are  not  merged. 

Expansion  of  a  directory  name  is  likely  to  be  radically  different  from  expansion  of  the  name  of  an 
ordinary  file:  the  exact  result  depends  on  the  remote  operating  system  and  FTP  server,  and  can  be 
previewed  by  doing  ‘mis  remote-files 

mget  and  mput  are  not  meant  to  transfer  entire  directory  subtrees  of  files.  You  can  do  this  by 
transferring  a  tar(l)  archive  of  the  subtree  (using  a  “representation  type”  of  “image”  as  set  by  the 
binary  command). 
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hash  Toggle  hash-sign  (#)  printing  for  each  data  block  transferred, 
help  [  command  ] 

Print  an  informative  message  about  the  meaning  of  command.  If  no  argument  is  given,  ftp  prints 
a  list  of  the  known  commands. 

led  [  directory  ] 

Change  the  working  directory  on  the  local  machine.  If  no  directory  is  specified,  the  user’s  home 
directory  is  used. 

Is  [  remote-directory  ]  [  local-file  ] 

Print  an  abbreviated  listing  of  the  contents  of  a  directory  on  the  remote  machine.  If  remote- 
directory  is  left  unspecified,  the  current  working  directory  is  used.  If  no  local  file  is  specified,  or  if 
local-file  is  the  output  is  sent  to  the  terminal. 

maedef  macro-name 

Define  a  macro.  Subsequent  lines  are  stored  as  the  macro  macro-name ;  a  null  line  (consecutive 
NEWLINE  characters  in  a  file  or  RETURN  characters  from  the  terminal)  terminates  macro  input 
mode.  There  is  a  limit  of  16  macros  and  4096  total  characters  in  all  defined  macros.  Macros 
remain  defined  until  a  close  command  is  executed. 

The  macro  processor  interprets  *$’  and  ‘\’  as  special  characters.  A  ‘$’  followed  by  a  number  (or 
numbers)  is  replaced  by  the  corresponding  argument  on  the  macro  invocation  command  line.  A 
'$’  followed  by  an  ‘i’  signals  that  macro  processor  that  the  executing  macro  is  to  be  looped.  On 
the  first  pass  ‘$i’  is  replaced  by  the  first  argument  on  the  macro  invocation  command  line,  on  the 
second  pass  it  is  replaced  by  the  second  argument,  and  so  on.  A  ‘\’  followed  by  any  character  is 
replaced  by  that  character.  Use  the  ‘\’  to  prevent  special  treatment  of  the  *$’. 

mdelete  [  remote-files  ] 

Delete  the  remote-files  on  the  remote  machine. 

mdir  remote-files  local-file 

Like  dir,  except  multiple  remote  files  may  be  specified.  If  interactive  prompting  is  on,  ftp  will 
prompt  the  user  to  verify  that  the  last  argument  is  indeed  the  target  local  file  for  receiving  mdir 
output 

mget  remote-files 

Expand  the  remote-files  on  the  remote  machine  and  do  a  get  for  each  file  name  thus  produced. 
See  glob  for  details  on  the  filename  expansion.  Resulting  file  names  will  then  be  processed 
according  to  case,  ntrans,  and  nmap  settings.  Files  are  transferred  into  the  local  working  direc¬ 
tory,  which  can  be  changed  with  "\cA  directory'’,  new  local  directories  can  be  created  with 
mkdir  directory'. 

mkdir  directory-name 

Make  a  directory  on  the  remote  machine. 

mis  remote-files  local-file 

Like  Is(lV),  except  multiple  remote  files  may  be  specified.  If  interactive  prompting  is  on,  ftp  will 
prompt  the  user  to  verify  that  the  last  argument  is  indeed  the  target  local  file  for  receiving  mb  out¬ 
put 

mode  [  mode-name  ] 

Set  the  “transfer  mode”  to  mode-name.  The  only  valid  mode-name  is  stream,  which  corresponds 
to  the  default  “stream”  mode. 

mput  local-files 

Expand  wild  cards  in  the  list  of  local  files  given  as  arguments  and  do  a  put  for  each  file  in  the 
resulting  list.  See  glob  for  details  of  filename  expansion.  Resulting  file  names  will  then  be  pro¬ 
cessed  according  to  ntrans  and  nmap  settings. 
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nmap  [  inpattern  outpattern  ] 

Set  or  unset  the  filename  mapping  mechanism.  If  no  arguments  are  specified,  the  filename  map¬ 
ping  mechanism  is  unset  If  arguments  are  specified,  remote  filenames  are  mapped  during  mput 
commands  and  put  commands  issued  without  a  specified  remote  target  filename.  If  arguments  are 
specified,  local  filenames  are  mapped  during  mget  commands  and  get  commands  issued  without  a 
specified  local  target  filename. 

This  command  is  useful  when  connecting  to  a  non-UNlX-system  remote  host  with  different  file 
naming  conventions  or  practices.  The  mapping  follows  the  pattern  set  by  inpattern  and  outpat¬ 
tern.  inpattern  is  a  template  for  incoming  filenames  (which  may  have  already  been  processed 
according  to  the  ntrans  and  case  settings).  Variable  templating  is  accomplished  by  including  the 
sequences  $1,  $2, . . . ,  $9  in  inpattern.  Use  \  to  prevent  this  special  treatment  of  the  $  character. 
All  other  characters  are  treated  literally,  and  are  used  to  determine  the  nmap  inpattern  variable 
values. 

For  example,  given  inpattern  $1.$2  and  the  remote  file  name  mydata.data,  $1  would  have  the 
value  “mydata”,  and  $2  would  have  the  value  “data”. 

The  outpattern  determines  the  resulting  mapped  filename.  The  sequences  $1,  $2,  . . . ,  $9  are 
replaced  by  any  value  resulting  from  the  inpattern  template.  The  sequence  $0  is  replaced  by  the 
original  filename.  Additionally,  the  sequence  *[seql  ,seq2  ]’  is  replaced  by  seql  if  seql  is  not  a 
null  string;  otherwise  it  is  replaced  by  seq2 . 

For  example,  the  command  'nmap  $1.$2.$3  [$l,$2].[$2,file]’  would  yield  the  output  filename 
myfile.data  for  input  filenames  myfile,data  and  myfile.data.old,  myfile.file  for  the  input  filename 
myfile,  and  myfile.myfile  for  the  input  filename  .myfile.  SPACE  characters  may  be  included  in 
outpattern,  as  in  the  example  'nmap  $1 1  sed  "s/  *$//"  >  $1’.  Use  the  \  character  to  prevent  spe¬ 
cial  treatment  of  the  ']’  and  characters. 

ntrans  [  inchars  [  outchars  ]  ] 

Set  or  unset  the  filename  character  translation  mechanism.  If  no  arguments  are  specified,  the 
filename  character  translation  mechanism  is  unset.  If  arguments  are  specified,  characters  in 
remote  filenames  are  translated  during  mput  commands  and  put  commands  issued  without  a 
specified  remote  target  filename,  and  characters  in  local  filenames  are  translated  during  mget 
commands  and  get  commands  issued  without  a  specified  local  target  filename. 

This  command  is  useful  when  connecting  to  a  non-UNDC-system  remote  host  with  different  file 
naming  conventions  or  practices.  Characters  in  a  filename  matching  a  character  in  inchars  are 
replaced  with  the  corresponding  character  in  outchars.  If  the  character’s  position  in  inchars  is 
longer  than  the  length  of  outchars,  the  character  is  deleted  from  the  file  name. 

open  host  [port  ] 

Establish  a  connection  to  the  specified  host  FTP  server.  An  optional  port  number  may  be  supplied, 
in  which  case,  ftp  will  attempt  to  contact  an  FTP  server  at  that  port  If  the  auto-login  option  is  on 
(default),  ftp  will  also  attempt  to  automatically  log  the  user  in  to  the  FTP  server  (see  below). 

prompt  Toggle  interactive  prompting.  Interactive  prompting  occurs  during  multiple  file  transfers  to  allow 
the  user  to  selectively  retrieve  or  store  files.  By  default,  prompting  is  turned  on.  If  prompting  is 
turned  off,  any  mget  or  mput  will  transfer  all  files,  and  any  mdelete  will  delete  all  files. 

proxy  ftp-command 

Execute  an  FTP  command  on  a  secondary  control  connection.  This  command  allows  simultaneous 
connection  to  two  remote  FTP  servers  for  transferring  files  between  the  two  servers.  The  first 
proxy  command  should  be  an  open,  to  establish  the  secondary  control  connection.  Enter  the  com¬ 
mand  ‘proxy  ?’  to  see  other  FTP  commands  executable  on  the  secondary  connection. 
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The  following  commands  behave  differently  when  prefaced  by  proxy:  open  will  not  define  new 
macros  during  the  auto-login  process,  close  will  not  erase  existing  macro  definitions,  get  and  mget 
transfer  files  from  the  host  on  the  primary  control  connection  to  the  host  on  the  secondary  control 
connection,  and  put,  mput,  and  append  transfer  files  from  the  host  on  the  secondary  control  con¬ 
nection  to  the  host  on  the  primary  control  connection. 

Third  party  file  transfers  depend  upon  support  of  the  PASV  command  by  the  server  on  the  secon¬ 
dary  control  connection. 

put  local-file  [  remote-file] 

Store  a  local  file  on  the  remote  machine.  If  remote-file  is  left  unspecified,  the  local  file  name  is 
used  after  processing  according  to  any  ntrans  or  nmap  settings  in  naming  the  remote  file.  File 
transfer  uses  the  current  settings  for  ‘‘representation  type”,  “file  structure”,  and  “transfer  mode”. 

pwd  Print  the  name  of  the  current  working  directory  on  the  remote  machine. 

quit  A  synonym  for  bye. 

quote  argl  arg2  . . . 

Send  the  arguments  specified,  verbatim,  to  the  remote  FTP  server.  A  single  FTP  reply  code  is 
expected  in  return. 

recv  remote-file  [  local-file] 

A  synonym  for  get. 

remotehelp  [  command-name  ] 

Request  help  from  the  remote  FTP  server.  If  a  command-name  is  specified  it  is  supplied  to  the 
server  as  well. 

rename  from  to 

Rename  the  file  from  on  the  remote  machine  to  have  the  name  to. 

reset  Clear  reply  queue.  This  command  re-synchronizes  command/reply  sequencing  with  the  remote 
FTP  server.  Resynchronization  may  be  necessary  following  a  violation  of  the  FTP  protocol  by  the 
remote  server. 

rmdir  directory-name 

Delete  a  directory  on  the  remote  machine. 

runique 

Toggle  storing  of  files  on  the  local  system  with  unique  filenames.  If  a  file  already  exists  with  a 
name  equal  to  the  target  local  filename  for  a  get  or  mget  command,  a  M’  is  appended  to  the 
name.  If  the  resulting  name  matches  another  existing  file,  a  *.2’  is  appended  to  the  original  name. 
If  this  process  continues  up  to  ‘.99’,  an  error  message  is  printed,  and  the  transfer  does  not  take 
place.  The  generated  unique  filename  will  be  reported.  Note:  runique  will  not  affect  local  files 
generated  from  a  shell  command  (see  below).  The  default  value  is  off. 

send  local-file  [  remote-file  ] 

A  synonym  for  put. 

sendport 

Toggle  the  use  of  PORT  commands.  By  default,  ftp  will  attempt  to  use  a  PORT  command  when 
establishing  a  connection  for  each  data  transfer.  The  use  of  PORT  commands  can  prevent  delays 
when  performing  multiple  file  transfers.  If  the  PORT  command  fails,  ftp  will  use  the  default  data 
port.  When  the  use  of  PORT  commands  is  disabled,  no  attempt  will  be  made  to  use  PORT  com¬ 
mands  for  each  data  transfer.  This  is  useful  when  connected  to  certain  FTP  implementations  that 
ignore  PORT  commands  but  incorrectly  indicate  they  have  been  accepted. 

status  Show  the  current  status  of  ftp. 
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struct  [  struct-name  ] 

Set  the  “file  structure”  to  struct-name.  The  only  valid  struct-name  is  file,  which  corresponds  to 
the  default  “file”  structure. 

sunique 

Toggle  storing  of  files  on  remote  machine  under  unique  file  names.  The  remote  FTP  server  must 
support  the  STOU  command  for  successful  completion.  The  remote  server  will  report  the  unique 
name.  Default  value  is  off. 

tenex  Set  the  “representation  type”  to  that  needed  to  talk  to  TENEX  machines, 
trace  Toggle  packet  tracing  (unimplemented), 

type  [  type-name  ] 

Set  the  “representation  type”  to  type-name .  The  valid  type-name  s  are  ascii  for  “network  ASCII”, 
binary  or  image  for  “image”,  and  tenex  for  “local  byte  size”  with  a  byte  size  of  8  (used  to  talk  to 
TENEX  machines).  If  no  type  is  specified,  the  current  type  is  printed.  The  default  type  is  “net¬ 
work  ASCn”. 

user  user-name  [password  ]  [  account  ] 

Identify  yourself  to  the  remote  FTP  server.  If  the  password  is  not  specified  and  the  server  requires 
it,  ftp  will  prompt  the  user  for  it  (after  disabling  local  echo).  If  an  account  field  is  not  specified, 
and  the  FTP  server  requires  it,  the  user  will  be  prompted  for  it.  If  an  account  field  is  specified,  an 
account  command  will  be  relayed  to  the  remote  server  after  the  login  sequence  is  completed  if  the 
remote  server  did  not  require  it  for  logging  in.  Unless  ftp  is  invoked  with  “auto-login”  disabled, 
this  process  is  done  automatically  on  initial  connection  to  the  FTP  server. 

verbose  Toggle  verbose  mode.  In  verbose  mode,  all  responses  from  the  FTP  server  are  displayed  to  the 
user.  In  addition,  if  verbose  mode  is  on,  when  a  file  transfer  completes,  statistics  regarding  the 
efficiency  of  the  transfer  are  reported.  By  default,  verbose  mode  is  on  if  ftp’s  commands  are  com¬ 
ing  from  a  terminal,  and  off  otherwise. 

?  [  command  ] 

A  synonym  for  help. 

Command  arguments  which  have  embedded  spaces  may  be  quoted  with  quote  (")  marks. 

If  any  command  argument  which  is  not  indicated  as  being  optional  is  not  specified,  ftp  will  prompt  for  that 
argument. 

ABORTING  A  FILE  TRANSFER 

To  abort  a  file  transfer,  use  the  terminal  interrupt  key  (usually  CTRL-C).  Sending  transfers  will  be  immedi¬ 
ately  halted.  Receiving  transfers  will  be  halted  by  sending  a  ftp  protocol  ABOR  command  to  the  remote 
server,  and  discarding  any  further  data  received.  The  speed  at  which  this  is  accomplished  depends  upon 
the  remote  server’s  support  for  ABOR  processing.  If  the  remote  server  does  not  support  the  ABOR  com¬ 
mand,  an  “ftp>”  prompt  will  not  appear  until  the  remote  server  has  completed  sending  the  requested  file. 

The  terminal  interrupt  key  sequence  will  be  ignored  when  ftp  has  completed  any  local  processing  and  is 
awaiting  a  reply  from  the  remote  server.  A  long  delay  in  this  mode  may  result  from  the  ABOR  processing 
described  above,  or  from  unexpected  behavior  by  the  remote  server,  including  violations  of  the  ftp  proto¬ 
col.  If  the  delay  results  from  unexpected  remote  server  behavior,  the  local  ftp  program  must  be  killed  by 
hand. 

FILE  NAMING  CONVENTIONS 

Local  files  specified  as  arguments  to  ftp  commands  are  processed  according  to  the  following  rules. 

1)  If  the  file  name  is  specified,  the  standard  input  (for  reading)  or  standard  output  (for  writing)  is 
used. 
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2)  If  the  first  character  of  the  file  name  is  ‘|\  the  remainder  of  the  argument  is  interpreted  as  a  shell 
command,  ftp  then  forks  a  shell,  using  popeii(3S)  with  the  argument  supplied,  and  reads  (writes) 
from  the  standard  output  (standard  input)  of  that  shell.  If  the  shell  command  includes  SPACE 
characters,  the  argument  must  be  quoted;  for  example  Is  -It”’.  A  particularly  useful  example 
of  this  mechanism  is:  ‘dir  j  more*. 

3)  Failing  the  above  checks,  if  “globbing”  is  enabled,  local  file  names  are  expanded  according  to  the 
rules  used  in  the  csh(l);  see  the  glob  command.  If  the  ftp  command  exf^cts  a  single  local  file  (for 
example,  put),  only  the  first  filename  generated  by  the  “globbing”  operation  is  used. 

4)  For  mget  commands  and  get  commands  with  unspecified  local  file  names,  the  local  filename  is  the 
remote  filename,  which  may  be  altered  by  a  case,  ntrans,  or  nmap  setting.  The  resulting  filename 
may  then  be  altered  if  runique  is  on. 

5)  For  mput  commands  and  put  commands  with  unspecified  remote  file  names,  the  remote  filename 
is  the  local  filename,  which  may  be  altered  by  a  ntrans  or  nmap  setting.  The  resulting  filename 
may  then  be  altered  by  the  remote  server  if  sunique  is  on. 

FILE  TRANSFER  PARAMETERS 

The  FTP  specification  specifies  many  parameters  which  may  affect  a  file  transfer. 

The  “representation  type”  may  be  one  of  “network  ASCn”,  “EBCDIC”,  “image”,  or  “local  byte  size”  with  a 
specified  byte  size  (for  PDP-lO’s  and  PDP-20’s  mostly).  The  “network  ASCH”  and  “EBCDIC”  types  have  a 
further  subtype  which  specifies  whether  vertical  format  control  (NEWLINE  characters,  form  feeds,  etc.)  are 
to  be  passed  through  (“non-print”),  provided  in  TELNET  format  (“TELNET  format  controls”),  or  provided 
in  ASA  (FORTRAN)  (“carriage  control  (ASA)”)  format,  ftp  supports  the  “network  ASCII”  (subtype  “non- 
print”  only)  and  “image”  types,  plus  “local  byte  size”  with  a  byte  size  of  8  for  communicating  with  TENEX 
machines. 

The  “file  structure”  may  be  one  of  “file”  (no  record  structure),  “record”,  or  “page”,  ftp  supports  only  the 
default  value,  which  is  “file”. 

The  “transfer  mode”  may  be  one  of  “stream”,  “block”,  or  “compressed”,  ftp  supports  only  the  default 
value,  which  is  “stream”. 

SEE  ALSO 

csh(l),  Is(lV),  rcp(lC),  tar(l),  popen(3S),  netrc(5),  ftpd(8C) 

BUGS 

Correct  execution  of  many  commands  depends  upon  proper  behavior  by  the  remote  server. 

An  error  in  the  treatment  of  carriage  returns  in  the  4.2  BSD  code  handling  transfers  with  a  “representation 
type”  of  “network  ASCII”  has  been  corrected.  This  correction  may  result  in  incorrect  transfers  of  binary 
files  to  and  from  4.2  BSD  servers  using  a  “representation  type”  of  “network  ASCII”,  Avoid  this  problem  by 
using  the  “image”  type. 
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NAME 

gcore  -  get  core  images  of  running  processes 
SYNOPSIS 

gcore  [  “O  filename  ]  process-id . . . 

DESCRIPTION 

gcore  creates  a  core  image  of  each  specified  process.  Such  an  image  can  be  used  with  adb(l)  or  dbx(l). 
The  name  of  the  core  image  file  for  the  process  whose  process  ID  is  process-id  will  be  CQr%.process-id. 

OPTIONS 

-o  filename  Substitute  filename  in  place  of  core  as  the  first  part  of  the  name  of  the  core  image  files. 

FILES 

coTe,process-id  core  images 

SEE  ALSO 

adb(l),  csh(l),  dbx(l),  kill(l),  ptrace(2) 
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NAME 

getopt  “  parse  command  options  in  shell  scripts 
SYNOPSIS 

set  —  ‘getopt  opstring  $*‘ 
set  argv  =  (‘getopt  opstring  $*‘) 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

getopt  breaks  up  options  in  command  lines  for  easy  parsing  by  shell  scripts,  and  checks  for  legal  options. 
optstring  is  a  string  of  option  letters  to  recognize,  (see  getopt(3)).  If  a  letter  is  followed  by  a  colon,  the 
option  is  expected  to  have  an  argument  —  which  may  or  may  not  be  separated  by  white  space. 

(The  ‘ — *  following  set  indicates  that  the  Bourne  shell  is  to  pass  arguments  beginning  with  a  dash  as 
parameters  to  the  script.) 

If  appears  on  the  command  line  that  invokes  the  script,  getopt  uses  it  to  delimit  the  end  of  options  it  is 
to  parse  (see  example  below).  If  used  explicitly,  getopt  will  recognize  it;  otherwise,  getopt  will  generate  it 
at  the  first  argument  it  encounters  that  has  no  In  either  case,  getopt  places  it  at  the  end  of  the  options. 
The  positional  parameters  ($1  $2. . . )  of  the  shell  are  reset  so  that  each  option  in  optstring  is  broken  out  and 
preceded  by  a  along  with  the  argument  (if  any)  for  each. 

EXAMPLE 

The  following  code  fragment  shows  how  one  might  process  the  arguments  for  a  command  that  can  take  the 
options  a  or  b,  as  well  as  the  option  o,  which  requires  an  argument: 

#!  /usr/bin/sh 

set  getopt  abo:  $*‘ 

if[$?!=0] 

then 

echo  $USAGE 
exit  2 
fi 

for  i  in  $* 
do 

case  $i  in 

-a  I  -b)  FLAG  =$i;  shift;; 

-0)  OARG=$2;shift2;; 

— )  shift;  break;; 

esac 

done 

This  code  will  accept  any  of  the  following  command  lines  as  equivalent: 
cmd  -a  -o  arg  fl  f2 
cmd-aoarg  fl  f2 
cmd-oarg-a  fl  f2 
cmd-a-oarg —  fl  f2 

SEE  ALSO 

csh(l),  getopts(l),  sh(l),  getopt(3) 

DIAGNOSTICS 

getopt  prints  an  error  message  on  the  standard  error  when  it  encounters  an  option  letter  not  included  in  opt¬ 
string. 
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NOTES 

getopts(l)  is  preferred. 
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NAME 

getopts,  getoptcvt  -  parse  command  options  in  shell  scripts 
SYNOPSIS 

getopts  optstring  name  [  argument, . .  ] 
getoptcvt  [  -b  ]  filename 
DESCRIPTION 

getopts  is  used  by  shell  procedures  to  parse  positional  parameters  and  to  check  for  legal  options.  It  should 
be  used  in  place  of  the  getopt(lV)  command.  It  supports  the  following  command  syntax  rules: 

•  Option  names  must  be  one  character  long. 

•  All  options  must  be  preceded  by 

•  Options  with  no  arguments  may  be  grouped  after  a  single  . 

•  Option-arguments  cannot  be  optional. 

•  All  options  must  precede  operands  on  the  command  line. 

•  ‘ — ’  may  be  used  to  indicate  the  end  of  the  options. 

optstring  must  contain  the  option  letters  the  command  using  getopts  will  recognize;  if  a  letter  is  followed 
by  a  colon,  the  option  is  expected  to  have  an  argument,  or  group  of  arguments,  which  must  be  separated 
from  it  by  white  space. 

Each  time  it  is  invoked,  getopts  will  place  the  next  option  in  the  shell  variable  name  and  the  index  of  the 
next  argument  to  be  processed  in  the  shell  variable  OPTIND.  Whenever  the  shell  or  a  shell  procedure  is 
invoked,  OPTIND  is  initialized  to  1. 

When  an  option  requires  an  option-argument,  getopts  places  it  in  the  shell  variable  OPTARG. 

If  an  illegal  option  is  encountered,  ?  will  be  placed  in  name. 

When  the  end  of  options  is  encountered,  getopts  exits  with  a  non-zero  exit  status.  The  special  option  ‘ — ’ 
may  be  used  to  delimit  the  end  of  the  options. 

By  default,  getopts  parses  the  positional  parameters.  If  extra  arguments  {argument . . .)  are  given  on  the 
getopts  command  line,  getopts  will  parse  them  instead. 

getoptcvt  reads  the  shell  script  in  filename,  converts  it  to  use  getopts  instead  of  getopt,  and  writes  the 
results  on  the  standard  output. 


OPTIONS 

getoptcvt 

-b  Generate  a  script  that  will  be  portable  to  earlier  releases  of  the  UNIX  system.  The  script  will 
determine  at  run  time  whether  to  invoke  getopts  or  getopt. 
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EXAMPLE 

The  following  fragment  of  a  shell  program  shows  how  one  might  process  the  arguments  for  a  command 
that  can  take  the  options  a  or  b,  as  well  as  the  option  o,  which  requires  an  option-argument: 

while  getopts  abo:  c 
do 


case  $c  in 
a|  b) 

FLAG=$c;; 

o) 

OARG=$OPTARG;; 

\?) 

echo  $USAGE 

esac 

exit  2;; 

done 

shift  ‘expr  $OPTIND  - 

This  code  will  accept  any  of  the  following  as  equivalent: 

cmd  -a  -b  -o  ”x3cx  z  yy*'  filename 
cmd  -a  -b  -o  ”xxx  z  yy”  —  filename 
cmd  -ab  -o  xxx,z,yy  filename 
cmd  -ab  -o  "xxx  z  yy"  filename 
cmd  -0  xxx,z,yy  -b  -a  filename 

SEE  ALSO 

getopt(lV),  sh(l),  getopt(3) 

WARNING 

Changing  the  value  of  the  shell  variable  OPTIND  or  parsing  different  sets  of  arguments  may  lead  to  unex¬ 
pected  results. 

DIAGNOSTICS 

getopts  prints  an  error  message  on  the  standard  error  when  it  encounters  an  option  letter  not  included  in 
optstring. 
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NAME 

get_selection  -  copy  the  contents  of  a  SunView  selection  to  the  standard  output 
SYNOPSIS 

get_selection  [  rank  ]  [  t  seconds  ]  [  D  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

get_selection  prints  the  contents  of  the  indicated  selection  on  standard  out.  A  selection  is  a  collection  of 
objects  (for  instance,  characters)  picked  with  the  mouse  in  the  SunView  window  system. 

OPTIONS 

rank  Indicate  which  selection  is  to  be  printed: 

1:  primary; 

2:  secondary; 

3:  clipboard. 

The  default  is  primary. 

t  seconds  Indicate  how  many  seconds  to  wait  for  the  holder  of  a  selection  to  respond  to  a  request 

before  giving  up.  The  default  is  6  seconds. 

D  Debugging.  Inquire  through  a  special  debugging  service  for  the  selection,  rather  than 

accessing  the  standard  service.  Useful  only  for  debugging  window  applications  which 
are  clients  of  the  selection  library. 

EXAMPLE 

The  following  line  in  a  SunView  root  menu  file  provides  a  menu  command  to  print  the  primary  selection 
on  the  user’s  default  printer: 

“Print  It”  sh  -c  get_s€lection  |  Ipr 

SEE  ALSO 

SunView  User’s  Guide 
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NAME 

gfxtool  -  run  graphics  programs  in  a  Sun  View  window 
SYNOPSIS 

gfxtool  [  -C  ]  [program  [  arguments  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

gfxtool  is  a  standard  tool  provided  with  the  SunView  environment  It  runs  graphics  programs  that  do  not 
overwrite  the  terminal  emulator  from  which  they  run. 

gfxtool  has  two  subwindows:  a  terminal  subwindow  and  an  empty  subwindow.  The  terminal  subwindow 
contains  a  running  shell,  just  like  the  shelltool  (see  shelltool(l)).  Programs  invoked  in  the  terminal  subwin¬ 
dow  can  run  in  the  empty  subwindow.  You  can  move  the  boundary  between  these  two  subwindows  as 
described  in  sunview(l).  If  you  wish,  you  can  make  gfxtool  your  console  by  entering  -C  as  the  first  argu¬ 
ment. 

Normally  you  can  use  the  mouse  and  keyboard  anywhere  in  the  empty  subwindow  to  access  frame  func¬ 
tions.  However,  some  graphics  programs  which  run  in  this  window  may  take  over  inputs  directed  to  it. 
For  example,  SunCore  uses  the  mouse  and  keyboard  for  its  own  input.  When  you  run  such  tools,  access 
the  Frame  Menu  from  the  tool  boundaries  or  frame  header. 

gfxtool  also  accepts  all  of  the  generic  tool  arguments;  see  sunview(l)  for  a  list  of  these  arguments. 

If  a  program  argument  is  present,  gfxtool  runs  it  If  there  are  no  arguments,  gfxtool  runs  the  program 
corresponding  to  your  SHELL  environment  variable.  If  this  environment  variable  is  not  available,  then 
gfxtool  runs  sh(l). 

OPTIONS 

-C  Redirect  system  console  oulput  to  this  instance  of  gfxtool. 

FILES 

7.ttyswrc 

/usr/demo/* 

SEE  ALSO 

sh(l),  shelltool(l),  sunview(l),  graphics_deinos(6) 

BUGS 

If  more  than  256  characters  are  input  to  a  terminal  emulator  subwindow  without  an  intervening  NEWLINE, 
the  terminal  emulator  may  hang.  If  this  occurs,  display  the  Frame  Menu;  the  ‘TTY  Hung?'  submenu  there 
has  one  item,  ‘Flush  input',  that  you  can  invoke  to  correct  the  problem. 
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NAME 

gprof  -  display  call-graph  profile  data 
SYNOPSIS 

gprof  [  -abcsz  ]  [  -e  fmcdon-mme  ]  [  function-name  ]  [  -f function-name  ]  [  -F  function-name  ] 

[  image-file  [  profile-file  . . .  ]  ] 

DESCRIPTION 

gprof  produces  an  execution  profile  of  a  program.  The  effect  of  called  routines  is  incorporated  in  the 
profile  of  each  caller.  The  profile  data  is  taken  from  the  call  graph  profile  file  which  is  created  by  programs 
compiled  with  the  -pg  option  of  cc(lV)  and  other  compilers.  That  option  also  links  in  versions  of  the 
library  routines  which  are  compiled  for  profiling.  The  symbol  table  in  the  executable  image  file  image-file 
(a.out  by  default)  is  read  and  correlated  with  the  call  graph  profile  file  profile-file  (gmon.out  by  default).  If 
more  than  one  profile  file  is  specified,  the  gprof  output  shows  the  sum  of  the  profile  information  in  the 
given  profile  files. 

First,  execution  times  for  each  routines  are  propagated  along  the  edges  of  the  call  graph.  Cycles  are 
discovered,  and  calls  into  a  cycle  are  made  to  share  the  time  of  the  cycle.  The  first  listing  shows  the  func¬ 
tions  sorted  according  to  the  time  they  represent,  including  the  time  of  their  call  graph  descendants.  Below 
each  function  entry  is  shown  its  (direct)  call-graph  children,  and  how  their  times  are  propagated  to  this 
function.  A  similar  display  above  the  function  shows  how  this  function’s  time  and  the  time  of  its  descen¬ 
dants  is  propagated  to  its  (direct)  call-graph  parents. 

Cycles  are  also  shown,  with  an  entry  for  the  cycle  as  a  whole  and  a  listing  of  the  members  of  the  cycle  and 
their  contributions  to  the  time  and  call  counts  of  the  cycle. 

Next,  a  flat  profile  is  given,  similar  to  that  provided  by  prof(l).  This  listing  gives  the  total  execution  times 
and  call  counts  for  each  of  the  functions  in  the  program,  sorted  by  decreasing  time.  Finally,  an  index  show¬ 
ing  the  correspondence  between  function  names  and  call-graph  profile  index  numbers. 

A  single  function  may  be  split  into  subfunctions  for  profiling  by  means  of  the  MARK  macro  (see  prof(3)). 

Beware  of  quantization  errors.  The  granularity  of  the  sampling  is  shown,  but  remains  statistical  at  best.  It 
is  assumed  that  the  time  for  each  execution  of  a  function  can  be  expressed  by  the  total  time  for  the  function 
divided  by  the  number  of  times  the  function  is  called.  Thus  the  time  propagated  along  the  call-graph  arcs 
to  parents  of  that  function  is  directly  proportional  to  the  number  of  times  that  arc  is  traversed. 

The  profiled  program  must  call  exit(2V)  or  return  normally  for  the  profiling  information  to  be  saved  in  the 
gmon.out  file. 

OPTIONS 

-a  Suppress  printing  statically  declared  functions.  If  this  option  is  given,  all  relevant  information 
about  the  static  function  (for  instance,  time  samples,  calls  to  other  functions,  calls  from  other  func¬ 
tions)  belongs  to  the  function  loaded  just  before  the  static  function  in  the  a.out  file. 

-b  Brief.  Suppress  descriptions  of  each  field  in  the  profile. 

-c  The  static  call-graph  of  the  program  is  discovered  by  a  heuristic  which  examines  the  text  space  of 
the  object  file.  Static-only  parents  or  children  are  indicated  with  call  counts  of  0. 

-s  Produce  a  profile  file  gmon.sum  which  represents  the  sum  of  the  profile  information  in  all  the 
specified  profile  files.  This  summary  profile  file  may  be  given  to  subsequent  executions  of  gprof 
(probably  also  with  a  -s)  option  to  accumulate  profile  data  across  several  runs  of  an  a.out  file. 

-z  Display  routines  which  have  zero  usage  (as  indicated  by  call  counts  and  accumulated  time).  This 
is  useful  in  conjunction  with  the  -c  option  for  discovering  which  routines  were  never  called. 

-e  function-name 

Suppress  printing  the  graph  profile  entry  for  routine  function-name  and  all  its  descendants  (unless 
they  have  other  ancestors  that  are  not  suppressed).  More  than  one  -e  option  may  be  given.  Only 
om  function-name  may  be  given  with  each  -e  option. 
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-E  function-name 

Suppress  printing  the  graph  profile  entry  for  routine  function-name  (and  its  descendants)  as  -e, 
above,  and  also  exclude  Uie  lime  spent  in  function-name  (and  its  descendants)  from  the  total  and 
percentage  time  computations.  More  than  one  -E  option  may  be  given.  For  example: 

‘-E  mcount  -E  mcleanup  ’ 
is  the  default. 

-f function-name 

Print  the  graph  profile  entry  only  for  routine  function-name  and  its  descendants.  More  than  one  ~f 
option  may  be  given.  Only  one  function-name  may  be  given  with  each  -f  option. 

-F  function-name 

Print  the  graph  profile  entry  only  for  routine  function-name  and  its  descendants  (as  -f,  above)  and 
also  use  only  the  times  of  the  printed  routines  in  total  time  and  percentage  computations.  More 
than  one  -F  option  may  be  given.  Only  one  function-name  may  be  given  with  each  ~F  option. 
The  “F  option  overrides  the  -E  option. 

ENVIRONMENT 

PROFDIR 

If  this  environment  variable  contains  a  value,  place  profiling  output  within  that  directory,  in  a  file 
named  pid.programname.  pid  is  the  process  ID,  and  programname  is  the  name  of  the  program 
being  profiled,  as  determined  by  removing  any  path  prefix  from  the  argv[0]  with  which  the  pro¬ 
gram  was  called.  If  the  variable  contains  a  NULL  value,  no  profiling  output  is  produced.  Other¬ 
wise,  profiling  output  is  placed  in  the  file  gmon.out. 

FILES 

a.out  executable  file  containing  namelist 

gmoii.out  dynamic  call-graph  and  profile 

gmon^sum  summarized  dynamic  call-graph  and  profile 

$PRO¥DlRfpid  ^programname 

SEE  ALSO 

cc(lV),  prof(l),  tcov(l),  exit(2V),  profil(2),  monitor(3),  prof(3) 

Graham,  S.L.,  Kessler,  P.B.,  McKusick,  M.K.,  ^gprof:  A  Call  Graph  Execution  Profiler \  Proceedings  of 
the  SIGPLAN  ’82  Symposium  on  Compiler  Construction,  SIGPLAN  Notices,  Vol.  17,  No.  6,  pp.  120-126, 
June  1982. 

BUGS 

Parents  which  are  not  themselves  profiled  will  have  the  time  of  their  profiled  children  propagated  to  them, 
but  they  will  appear  to  be  spontaneously  invoked  in  the  call-graph  listing,  and  will  not  have  their  time  pro¬ 
pagated  further.  Similarly,  signal  catchers,  even  though  profiled,  will  appear  to  be  spontaneous  (although 
for  more  obscure  reasons).  Any  profiled  children  of  signal  catchers  should  have  their  times  propagated 
properly,  unless  the  signal  catcher  was  invoked  during  the  execution  of  the  profiling  routine,  in  which  case 
all  is  lost. 
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NAME 

graph  -  draw  a  graph 
SYNOPSIS 

graph  [  -a  spacing  [  start  ]  ]  [  -b  ]  [  -c  string  ]  [  -g  gridstyle  ]  [  -1  label  ] 

[  —m  connectmode  ]  [  -s  ]  [  -x  [  1  ]  lower  [  upper  [  spacing  ]  ]  ] 

[  -y  [  1  ]  lower  [  upper  [  spacing  ]  ]  ]  [  -h  fraction  ]  [  -w  fraction  ]  [  -r  fraction  ] 

[  -u  fraction  ]  [  -t  ] . . . 

DESCRIPTION 

graph  with  no  options  takes  pairs  of  numbers  from  the  standard  input  as  abscissaes  and  ordinates  of  a 
graph.  Successive  points  are  connected  by  straight  lines.  The  standard  output  from  graph  contains  plotting 
instructions  (see  plot(5))  suitable  for  input  to  plot(lG)  or  to  the  command  Ipr  -g  (see  Ipr(l)). 

If  the  coordinates  of  a  point  are  followed  by  a  nonnumeric  string,  that  string  is  printed  as  a  label  beginning 
on  the  point.  Labels  may  be  surrounded  with  quotes  in  which  case  they  may  be  empty  or  contain 
blanks  and  numbers;  labels  never  contain  NEWLINE  characters. 

A  legend  indicating  grid  range  is  produced  with  a  grid  unless  the  -s  option  is  present. 


OPTIONS 

Each  option  is  recognized  as  a  separate  argument.  If  a  specified  lower  limit  exceeds  the  upper  limit,  the 
axis  is  reversed. 


-a  spacingi  start  ] 


-b 

-c  string 
-g  gridstyle 

~l 

-m  connectmode 

-s 


Supply  abscissaes  automatically  (they  are  missing  from  the  input);  spacing  is  the 
spacing  (default  1).  start  is  the  starting  point  for  automatic  abscissaes  (default  0  or 
lower  limit  given  by  -x). 

Break  (disconnect)  the  graph  after  each  label  in  the  input. 

String  is  the  default  label  for  each  point. 

Gridstyle  is  the  grid  style:  0  no  grid,  1  frame  with  ticks,  2  full  grid  (default). 
label  is  label  for  graph. 

Mode  (style)  of  connecting  lines:  0  disconnected,  1  connected  (default).  Some  dev¬ 
ices  give  distinguishable  line  styles  for  other  small  integers. 

Save  screen,  do  not  erase  before  plotting. 


-X  [  1  ]  lower  [  upper  [  spacing  ]  ] 

If  I  is  present,  x  axis  is  logarithmic,  lower  and  iq)p€r  are  lower  (and  upper)  x  limits. 
spacing^  if  present,  is  grid  spacing  on  x  axis.  Normally  these  quantities  are  deter¬ 
mined  automatically. 


-y  [  1  ]  lower  [  upper  [  spacing  ]  ] 

If  1  is  present,  y  axis  is  logarithmic,  lower  and  upper  are  lower  (and  upper)  y  limits. 
spacing,  if  present,  is  grid  spacing  on  y  axis.  Normally  these  quantities  are  deter¬ 
mined  automatically. 

-h  fraction  fraction  of  space  for  height. 


-w  fraction 
~T  fraction 
-u  fraction 

-t 


fraction  of  space  for  width. 

fraction  of  space  to  move  right  before  plotting. 

fraction  of  space  to  move  up  before  plotting. 

Transpose  horizontal  and  vertical  axes.  Option  -x  now  applies  to  the  vertical  axis. 


SEE  ALSO 

Ipr(l),  pIot(lG),  spline(lG) 
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BUGS 

graph  stores  all  points  internally  and  drops  those  for  which  there  is  no  room. 
Segments  that  run  out  of  bounds  are  dropped,  not  windowed. 

Logarithmic  axes  may  not  be  reversed. 
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NAME 

grep,  egrep,  fgrep  -  search  a  file  for  a  string  or  regular  expression 
SYNOPSIS 

grep  [  -bchilnsvw  ]  [  -e  expression  ]  [filename. . .  ] 

egrep  [ -bchilnsv  ]  [  -e  expression  ]  [ -f filename  ]  [  expression ]  [filename.. .  ] 
fgrep  [  -bchilnsvx  ]  [  -e  string  ]  [  -f filename  ]  [  string  ]  [filename . . .  ] 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/grep  [ -bchilnsvw ]  [ -e  expression  ]  [filename.. .  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

Commands  of  the  grep  family  search  the  input  filenames  (the  standard  input  default)  for  lines  matching  a 
pattern.  Normally,  each  line  found  is  copied  to  the  standard  output,  grep  patterns  are  limited  regular 
expressions  in  the  style  of  ed(I).  egrep  patterns  are  full  regular  expressions  including  alternation,  fgrep 
patterns  are  fixed  strings  —  no  regular  expression  metacharacters  are  supported. 

In  general,  egrep  is  the  fastest  of  these  programs. 

Take  care  when  using  the  characters  *$’,  [,  ‘|’,  ‘(’» *)’>  and  ‘\’  in  the  expression,  as  these  characters 

are  also  meaningful  to  the  shell.  It  is  safest  to  enclose  the  entire  expression  argument  in  single  quotes 

When  any  of  the  grep  utilities  is  applied  to  more  than  one  input  file,  the  name  of  the  file  is  displayed 
preceding  each  line  which  matches  the  pattern.  The  filename  is  not  displayed  when  processing  a  single  file, 
so  if  you  actually  want  the  filename  to  appear,  use  /dev/null  as  a  second  file  in  the  list. 

OPTIONS 

-b  Precede  each  line  by  the  block  number  on  which  it  was  found.  This  is  sometimes  useful  in  locat¬ 
ing  disk  block  numbers  by  context. 

-c  Display  a  count  of  matching  lines  rather  than  displaying  the  lines  which  match. 

-h  Do  not  display  filenames. 

-i  Ignore  the  case  of  letters  in  making  comparisons  —  that  is,  upper  and  lower  case  are  considered 
identical. 

-I  List  only  the  names  of  files  with  matching  lines  (once)  separated  by  NEWLINE  characters. 

-n  Precede  each  line  by  its  relative  line  number  in  the  file. 

~s  Work  silently,  that  is,  display  nothing  except  error  messages.  This  is  useful  for  checking  the  error 
status. 

-V  Invert  the  search  to  only  display  lines  that  do  not  match. 

-w  Search  for  the  expression  as  a  word  as  if  surrounded  by  \<  and  \>.  This  applies  to  grep  only. 

-Y  Display  only  those  lines  which  match  exactly  —  that  is,  only  lines  which  match  in  their  entirety. 

This  applies  to  fgrep  only. 

-e  expression 

Same  as  a  simple  expression  argument,  but  useful  when  the  expression  begins  with  a 

-e  string 

For  fgrep  the  argument  is  a  literal  character  string. 

— f  filename 

Take  the  regular  expression  (egrep)  or  a  list  of  strings  separated  by  NEWLINE  (fgrep)  from 
filename. 
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SYSTEM  V  OPTIONS 

The  -s  option  to  grep  indicates  that  error  messages  for  nonexistent  or  unreadable  files  should  be 
suppressed,  not  that  all  messages  except  for  error  messages  should  be  suppressed. 

REGULAR  EXPRESSIONS 

The  following  one-character  regular  expressions  match  a  single  character: 

c  An  ordinary  character  (not  one  of  the  special  characters  discussed  below)  is  a  one-character  regu¬ 
lar  expression  that  matches  that  character. 

Vr  A  backslash  (\)  followed  by  any  si)ecial  character  is  a  one-character  regular  expression  that 
matches  the  special  character  itself.  The  special  characters  are: 

•  ‘ and  ‘\*  (period,  asterisk,  left  square  bracket,  and  backslash,  respec¬ 
tively),  which  are  always  special,  except  when  they  appear  within  square  brack¬ 
ets  ([]). 

•  (caret  or  circumflex),  which  is  special  at  the  beginning  of  an  entire  regular 
expression,  or  when  it  immediately  follows  the  left  of  a  pair  of  square  brackets 
([]). 

•  $  (currency  symbol),  which  is  special  at  the  end  of  an  entire  regular  expression. 

A  backslash  followed  by  one  of  *<’,  *>’,  *(’,  ‘)’,  *{’,  or  *}’,  represents  a  special  operator  in  the  regular 
expression;  see  below. 

.  A  (period)  is  a  one-character  regular  expression  that  matches  any  character  except  NEWLINE. 

[  string  ] 

A  non-empty  string  of  characters  enclosed  in  square  brackets  is  a  one-character  regular  expression 
that  matches  any  one  character  in  that  string.  If,  however,  the  first  character  of  the  string  is  a 
(a  circumflex  or  caret),  the  one-character  regular  expression  matches  any  character  except  NEW- 
LINE  and  the  remaining  characters  in  the  string.  The  has  this  special  meaning  only  if  it  occurs 
first  in  the  string.  The  (minus)  may  be  used  to  indicate  a  range  of  consecutive  ASCII  charac¬ 
ters;  for  example,  [0~9]  is  equivalent  to  [0123456789].  The  loses  this  special  meaning  if  it 
occurs  first  (after  an  initial  if  any)  or  last  in  the  string.  The  *]’  (right  square  bracket)  does  not 
terminate  such  a  string  when  it  is  the  first  character  within  it  (after  an  initial  if  any);  that  is, 
[  ]a-f]  matches  either  *]'  (a  right  square  bracket )  or  one  of  the  letters  a  through  f  inclusive.  The 
four  characters  ‘[  ’,  and  ‘V  stand  for  themselves  within  such  a  string  of  characters. 

The  following  rules  may  be  used  to  construct  regular  expressions: 

*  A  one-character  regular  expression  followed  by  (an  asterisk)  is  a  regular  expression  that 
matches  zero  or  more  occurrences  of  the  one-character  regular  expression.  If  there  is  any  choice, 
the  longest  leftmost  string  that  permits  a  match  is  chosen. 

\(and\)  A  regular  expression  enclosed  between  the  character  sequences  \(  and  \)  matches  whatever  the 
unadorned  regular  expression  matches.  This  applies  only  to  grep. 

\n  The  expression  \n  matches  the  same  string  of  characters  as  was  matched  by  an  expression 
enclosed  between  \(  and  \)  earlier  in  the  same  regular  expression.  Here  /t  is  a  digit;  the  sub¬ 
expression  specified  is  that  beginning  with  the  «th  occurrence  of  \(  counting  from  the  left.  For 
example,  the  expression  *\(.*\)\1$  matches  a  line  consisting  of  two  repeated  appearances  of  the 
same  string. 

Concatenation 

The  concatenation  of  regular  expressions  is  a  regular  expression  that  matches  the  concatenation  of  the 
strings  matched  by  each  component  of  the  regular  expression. 

\<  The  sequence  \<  in  a  regular  expression  constrains  the  one-character  regular  expression  immedi¬ 
ately  following  it  only  to  match  something  at  the  beginning  of  a  “word”;  that  is,  either  at  the 
beginning  of  a  line,  or  just  before  a  letter,  digit,  or  underline  and  after  a  character  not  one  of  these. 
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\>  The  sequence  \>  in  a  regular  expression  constrains  the  one-character  regular  expression  immedi¬ 
ately  following  it  only  to  match  something  at  the  end  of  a  "word”;  that  is,  either  at  the  end  of  a 
line,  or  just  before  a  character  which  is  neither  a  letter,  digit,  nor  underline. 

\{m\} 

\{m,\} 

A  regular  expression  followed  by  or  matches  a  range  of  occurrences  of  the 

regular  expression.  The  values  of  m  and  n  must  be  non-negative  integers  less  than  256;  \{m\} 
matches  exactly  m  occurrences;  \{m,\}  matches  at  least  m  occurrences;  matches  any 

number  of  occurrences  between  m  and  «  inclusive.  Whenever  a  choice  exists,  the  regular  expres¬ 
sion  matches  as  many  occurrences  as  possible. 

A  circumflex  or  caret  (  )  at  the  beginning  of  an  entire  regular  expression  constrains  that  regular 
expression  to  match  an  initial  segment  of  a  line. 

$  A  currency  symbol  ($)  at  the  end  of  an  entire  regular  expression  constrains  that  regular  expression 
to  match  a  final  segment  of  a  line. 

The  construction 

example%  ^entire  regular  expression  $ 
constrains  the  entire  regular  expression  to  match  the  entire  line. 

egrep  accepts  regular  expressions  of  the  same  sort  grep  does,  except  for  \(,  \),  Vi.  \<,  \>,  \{,  and  \},  with  the 
addition  of: 

*  A  regular  expression  (not  just  a  one-character  regular  expression)  followed  by 
(an  asterisk)  is  a  regular  expression  that  matches  zero  or  more  occurrences 
of  the  one-character  regular  expression.  If  there  is  any  choice,  the  longest  left¬ 
most  string  that  permits  a  match  is  chosen, 

+  A  regular  expression  followed  by  *+’  (a  plus  sign)  is  a  regular  expression  that 
matches  one  or  more  occurrences  of  the  one-character  regular  expression.  If 
there  is  any  choice,  the  longest  leftmost  string  that  permits  a  match  is  chosen. 

?  A  regular  expression  followed  by  "V  (a  question  mark)  is  a  regular  expression 
that  matches  zero  or  one  occurrences  of  the  one-character  regular  expression.  If 
there  is  any  choice,  the  longest  leftmost  string  that  permits  a  match  is  chosen. 

I  Alternation:  two  regular  expressions  separated  by  T  or  NEWLINE  match  either 
a  match  for  the  first  or  a  match  for  the  second. 

0  A  regular  expression  enclosed  in  parentheses  matches  a  match  for  the  regular 
expression. 

The  order  of  precedence  of  operators  at  the  same  parenthesis  level  is  ‘[  ]’  (character  classes),  then  '+* 
*?’  (closures), then  concatenation,  then  ‘|’  (alternation)and  NEWLINE. 

EXAMPLES 

Search  a  file  for  a  fixed  string  using  fgrep: 

example  %  fgrep  intro /usr/share/man/man3/*.3* 

Look  for  character  classes  using  grep: 

example%  grep  ’[1-8]([CJMSNX])’  /usr/share/man/man  1/^,1 
Look  for  alternative  patterns  using  egrep: 

example%  egrep  *(SaUy|Fred)  (Smith|Jones|Parker)’  telephonedist 
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To  get  the  filename  displayed  when  only  processing  a  single  file,  use/dev/null  as  the  second  file  in  the  list- 
example  %  grep  ’Sally  Parker’  telephone.Ust /dev/null 

FILES 

/dev/null 
SEE  ALSO 

awk(l),  ed(l),  ex(l),  sh(l),  vi(l),  sed(lV) 

BUGS 

Lines  are  limited  to  1024  characters  by  grep;  longer  lines  are  truncated. 

The  combination  of  —I  and  — v  options  does  not  produce  a  list  of  files  in  which  a  regular  expression  is  not 
found.  To  get  such  a  list,  use  the  Bourne  shell  construct 

for  filename  in  * 

do 

if  [  ‘grep  "re”  %filename  |  wc  -l‘  -eq  0  ] 
then 

echo  ^filename 
fi 

done 

or  the  C  shell  construct: 

foreach  filename  (*) 

if  (‘grep  "re"  Sfilename  |  wc  -l‘  ==  0)  echo  $filename 

end 

Ideally  there  should  be  only  one  grep. 

DIAGNOSTICS 

Exit  status  is  0  if  any  matches  are  found,  1  if  none,  2  for  syntax  errors  or  inaccessible  files. 
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NAME 

groups  -  display  a  user’s  group  memberships 
SYNOPSIS 

groups  [  username  . . .  ] 

DESCRIPTION 

With  no  arguments,  groups  displays  the  groups  to  which  you  belong;  else  it  displays  the  groups  to  which 
the  username  belongs.  Each  user  belongs  to  a  group  specified  in  the  password  file  /etc/passwd  and  possi¬ 
bly  to  other  groups  as  specified  in  the  file  /etc/group.  If  you  do  not  own  a  file  but  belong  to  the  group 
which  it  is  owned  by  then  you  are  granted  group  access  to  the  file. 

FILES 

/etc/passwd 

/etc/group 

SEE  ALSO 

getgroups(2V) 
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NAME 

head  -  display  first  few  lines  of  specified  files 
SYNOPSIS 

head  [  -n  ]  [filename. . .] 

DESCRIPTION 

head  copies  the  first  n  lines  of  each  filename  to  the  standard  output.  If  no  filename  is  given,  head  copies 
lines  from  the  standard  input.  The  default  value  of  n  is  10  lines. 

When  more  than  one  file  is  specified,  the  start  of  each  file  which  looks  like: 

==>filename<== 

Thus,  a  common  way  to  display  a  set  of  short  files,  identifying  each  one,  is: 
example  %  head  -9999  filename  1  filename2  . . . 

EXAMPLE 

The  following  example: 

example  %  head  -4  /usr/share/man/maiil/{cat,head4ail},l* 
produces: 

==>  /usr/share/man/manl/cat.lv  <== 

.TH  CAT  IV  "2  June  1983" 

.SH  NAME 

cat  —  concatenate  and  display 
.SH  SYNOPSIS 

==>  /usr/share/man/manl/head.l  <== 

.TH  HEAD  1  "24  August  1983" 

.SH  NAME 

head  -  display  first  few  lines  of  specified  files 
.SH  SYNOPSIS 

==>  /usr/share/man/manl/tail.l  <== 

.THTAILl  "27  April  1983" 

.SH  NAME 

tail  -  display  the  last  part  of  a  file 
.SH  SYNOPSIS 

SEE  ALSO 

cat(lV),  more(l),  tail(l) 
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NAME 

heIp_open  -  use  help_viewer  to  open  a  file 
SYNOPSIS 

help_open  [  -a  ]  [filename  [  pagejtumber  ]  ] 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4  1  release 
feature. 

DESCRIPTION 

help_open  is  used  to  cause  a  running  help>ewer(l)  to  open  a  file,  filename  is  typically  the  name  of  a 
help_viewer  file.  A  call  is  made  to  help__viewer  using  the  same  RPC  mechanism  as  is  used  by  Spot  Help. 

If  filename  is  relative,  help_viewer  looks  for  it  relative  to  the  default  help  directory  (as  defined  in  the 
user  s  .defaults  database).  Otherwise,  help_viewer  treats  filename  as  an  absolute  pathname. 

If  the  RPC  call  to  help__viewer  fails,  help^open  attempts  to  spawn  help_viewer,  ^ith  filename  as  a  com^ 
mand  line  argument.  If  the  -a  command  line  option  was  given,  then  filename  is  first  converted  to  an  abso¬ 
lute  pathname,  as  described  in  OPTIONS,  below, 

OPTIONS 

-a  Cony Qn  filename  to  an  absolute  pathname.  This  option  causes  help_open  to  get  the  current  work¬ 

ing  directory  and  append  it  to  the  front  of  filename  (thus  creating  an  absolute  pathname)  before 
po&sing  filename  on  to  help_viewer.  This  allows  help_open  to  be  used  with  other  processes,  such 
as  Sun  Org^izer  (see  organizer(l)),  which  deal  in  relative  pathnames.  The  -a  option  has  no 
effect  if  filename  begins  with  the  character  7*. 

EXAMPLES 

In  the  first  example,  help^viewer  opens  the  file  help/HeIp_Basics.  This  file  is  located  relative  to  the 
default  help  directory  (as  defined  in  the  user’s  .defaults  database).  If  the  default  help  directory  is  set  to 
/voI/help/language/USA-English,  this  is  /vol/help/language/USA-English/help/Help_Basics. 

example  %  lieIp_open  help/Help__Basics 
example  % 

The  second  example  is  the  same  as  the  first,  but  it  opens  Help^Basics  to  page  3. 

example%  help  open  “help/HeIp_Basics  3” 
example  % 

In  the  next  example,  help_viewer  opens  somefile  using  the  absolute  pathname,  /home/mtravis/somefile. 

example%  help^open  /home/mtravis/somefile 
example  % 

In  the  last  example,  help  viewer  opens  /home/ahinkle/anotherfile. 

example%  cd  /home/ahinkle 
example  %  help_open  —a  anotherfile 
example  %  ’ 

FILES 

/usr/lib/help/* 

SEE  ALSO 

lielp__viewer(l),  organizer(l),  help(5),  help_viewer(5) 
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Sun386i  Developer' s  Guide 


Sun  Release  4.1 


Last  change:  21  January  1990 


229 


HELP_VIEWER(1) 


USER  COMMANDS 


HELP_VIEWER(1) 


NAME 

help_viewer  -  SunView  application  providing  help  with  applications  and  desktop 
SYNOPSIS 

/usr/lib/help_viewer  [  -A  time  ]  [  ~dir  dirname  ]  [filename  [#  ]  ] 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

help_viewer  accesses  help  documentation  about  SunView  applications  and  the  SunView  Desktop.  This 
help  consists  of  intermixed  text  and  graphics  This  help  consists  of  intermixed  text  and  graphics  displayed 
in  a  window  called  the  Help  Viewer. 

You  start  and  control  help_viewer  by  one  of  these  methods: 

•  Typing  help_viewer  at  a  shell  prompt. 

•  Clicking  on  the  More  Help  button  in  a  Spot  Help  window. 

•  Sending  instructions  to  the  Help  Viewer  using  the  help_open  command. 

filename  is  the  name  of  startup  file  relative  to  help  directory  (or  /vol/help  by  default,  as  set  in  the  Help 
category  of  defaultsedit).  #  is  a  page  number  separated  from  the  filename  by  a  SPACE.  If  #  is  omitted,  the 
first  page  is  shown. 

The  documentation  within  help_viewer  is  extensible,  but  as  shipped  it  includes  handbooks  for  the  Desktop, 
inailtool(l),  shelltool(l),  textedit(l),  sunview(l),  organizer(l),  dos(l),  coloredit(l),  snap(l),  and  itself 
(help_viewer). 

Developers  and  users  can  include  additional  handbooks  by  modifying  /voI/help/fonnat/Top_Level.  See 
help_viewer(5). 

The  user  moves  between  the  various  pages  of  help  with  the  assistance  of  hypertext  links.  Links  are  con¬ 
nections  between  pages  of  text.  The  convention  is  to  use  underlined  text  to  indicate  the  presence  of  a  link. 
When  the  user  double-clicks  on  a  link,  the  text  associated  with  the  topic  indicated  by  the  link  is  shown  in 
the  Help  Viewer.  There  are  links  in  many  places  to  make  it  quick  and  easy  to  go  from  place  to  place  within 
the  help_viewer  database. 

Many  help  topics  contain  more  than  one  page  of  text.  In  these  cases,  links  to  the  next  page  and  to  the  pre¬ 
vious  page  are  available  at  the  upper-right  comer  of  the  Help  Viewer,  allowing  the  user  to  page  through  the 
document. 

The  user’s  current  position  within  the  hierarchy  of  text  is  indicated  by  the  links  at  the  upper-left  comer  of 
the  Help  Viewer.  The  last  link  in  the  list  is  the  level  just  above  the  user’s  current  position. 

OPTIONS 

The  standard  SunView  options  for  window  size,  position,  fonts,  and  other  options  are  accepted.  But  note 
that  the  font  setting  only  affects  the  font  in  the  Help  Viewer  namestripe.  Also,  Help  Viewer  text  does  not 
wrap  as  a  window  is  resized.  See  sunview(l)  for  details. 

-A  time  Sets  autoclose  for  time  minutes.  If  the  help  window  is  not  used  for  time  minutes,  it 

closes  automatically. 

-dir  dirname  Name  of  the  help  directory 

FILES 

/vol/help  automount  point  of  miscellaneous  help  files 

The  files  in  /usr/lib/help  are  used  by  the  help  and  the  help_viewer  facilities,  and  the  SCCS  sccs-help(l) 
facility. 
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Dir^tories  within  /usr/lib/help  named  after  SunView  applications  and  the  Desktop  contain  specific  infor¬ 
mation  used  by  help_viewer.  See  help_viewer(5)  for  information  about  the  files  in  these  directories. 

SEE  ALSO 

sccs-help(l),  mailtool(l),  shelltool(l),  textedit(l),  heIp_open(l),  help_viewer(5) 

Sun386i  User's  Guide 
Sun386i  Developer's  Guide 
DIAGNOSTICS 

help_viewer(l)  displays  a  pop-up  error  window  if  it  cannot  find  the  file  required  to  show  the  requested 
help. 
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NAME 

hostid  ”  print  the  numeric  identifier  of  the  current  host 

SYNOPSIS 

hostid 

DESCRIPTION 

The  hostid  command  prints  the  identifier  of  the  current  host  in  hexadecimal.  This  numeric  value  is  unique 
across  all  Sun  hosts. 

SEE  ALSO 

gethostid(2) 
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NAME 

hostname  -  set  or  print  name  of  current  host  system 
SYNOPSIS 

hostname  [  name-of-host  ] 

DESCRIPTION 

The  hostname  command  prints  the  name  of  the  current  host,  as  given  before  the  “login”  prompt.  The 
super-user  can  set  the  hostname  by  giving  an  argument;  this  is  usually  done  in  the  startup  script 
/etc/rc.local. 

FILES 

/etc/rc.Iocal 

SEE  ALSO 

gethostname(2) 
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NAME 

iconedit  -  create  and  edit  images  for  SunView  icons,  cursors  and  panel  items 

SYNOPSIS 

iconedit  [filename  ] 

OPTIONS 

iconedit  accepts  the  standard  SunView  command-line  arguments;  see  sunview(l)  for  a  list. 

AVAILABILITY 

This  command  is  available  with  the  SunView  User's  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

iconedit  is  a  standard  tool  provided  with  the  SunView  environment.  With  it  you  can  create  and  edit  small 
images  for  use  in  icons,  cursors,  panel  items,  etc.  iconedit  has  several  subwindows: 

•  A  large  drawing  area  or  canvas  (on  the  left). 

•  A  small  proof  area  for  previewing  a  life-size  version  of  the  image  being  edited  (at  the  lower 
right). 

•  A  control  panel  showing  the  options  available  and  their  current  state  (at  the  center  right). 

•  An  area  for  status  messages  (at  the  upper  right). 

•  An  area  containing  instructions  for  the  use  of  the  mouse  (above  the  drawing  canvas). 

Inside  the  canvas,  use  the  left  button  to  draw  and  the  middle  button  to  erase.  As  you  draw,  an  enlarged  ver¬ 
sion  of  the  image  appears  in  the  canvas,  while  a  life-sized  version  of  the  image  appears  in  the  proof  area. 
Use  the  right  button  to  undo  the  previous  operation. 

While  editing  a  cursor  image,  you  can  try  the  cursor  out  against  different  backgrounds  and  with  different 
raster  operations  by  moving  the  cursor  into  the  proof  area. 

CONTROL  PANEL 

The  large  control  panel  to  the  right  of  the  canvas  contains  many  items  through  which  you  can  control 
iconedit.  Some  items  are  buttons  which  allow  you  to  initiate  commands,  some  are  text  fields  which  you 
type  into,  and  some  are  choice  items  allowing  you  select  from  a  range  of  options.  Use  the  left  button  to 
select  items.  Most  items  also  have  a  menu  which  you  can  invoke  with  the  right  button. 

There  are  three  text  fields:  the  two  at  the  top  labeled  Dir:  and  File:,  and  one  to  the  right  of  the  abc  labeled 
Fill:.  A  triangular  caret  points  to  the  current  type-in  position.  Typing  RETURN  advances  the  caret  to  the 
next  text  field;  you  can  also  move  the  caret  to  a  text  field  by  selecting  the  field  with  the  left  button. 

Each  item  in  the  control  panel  is  described  below: 

Dir  The  current  directory. 

File  The  current  filename.  The  default  is  the  filename  given  on  the  command  line.  You  can  request 
filename  completion  by  pressing  ESC.  iconedit  searches  the  current  directory  for  files  whose 
names  begin  with  the  string  you  entered.  If  the  filename  search  locates  only  one  file,  that  file  will 
be  loaded  in.  In  addition,  typing  CTRL-L,  CTRL-S,  CTRL-B  or  CTRL-Q  are  equivalent  to  pressing 
the  Load,  Store,  Browse,  or  Quit  buttons,  respectively. 

Load  (Button)  Load  the  canvas  from  the  file  named  in  the  File  field. 

Store  (Button)  Store  the  current  image  in  the  file  named  in  the  File  field. 

Browse  (Button)  Display  all  the  images  in  the  current  directory  in  a  popup  panel.  When  you  select  an 

image  with  the  left  button,  it  will  be  loaded  into  the  canvas  for  editing  and  the  browsing  panel  will 

be  hidden.  Pressing  browse  again  will  cause  the  panel  to  popup  again  (it  will  come  up  immedi¬ 
ately  if  the  directory  and  file  fields  have  not  been  modified). 

Quit  (Button)  Terminate  processing.  Quitting  requires  confirmation. 


234 


Last  change:  2  October  1989 


Sun  Release  4.1 


ICONEDIT(l) 


USER  COMMANDS 


ICONEDIT(l) 


Size  Alter  the  canvas  size.  Choices  are  icon  size  (64  x  64  pixels)  or  cursor  size  (16  x  16  pixels). 

Grid  Display  a  grid  over  the  drawing  canvas,  or  turn  the  grid  off. 

Clear  (Button)  Clear  the  canvas. 

Fill  (Button)  Fill  canvas  with  current  rectangular  fill  pattern. 

Invert  (Button)  Invert  each  pixel  represented  on  the  canvas. 

Paintbrush 

Select  from  among  five  painting  modes.  Instructions  for  each  painting  mode  appear  above  the 
canvas.  The  painting  modes  are: 

dot  Paint  a  single  dot  at  a  time. 

line  Draw  a  line.  To  draw  a  line  on  the  canvas,  point  to  the  first  endpoint  of  the  line,  and 
press  and  hold  the  left  mouse  button.  While  holding  the  button  down,  drag  the  cursor  to 
the  second  endpoint  of  the  line.  Release  the  mouse  button. 

rectangle 

Draw  a  rectangle.  To  draw  a  rectangle  on  the  canvas,  point  to  the  first  comer  of  the  rec¬ 
tangle  and  press  and  hold  the  left  mouse  button.  While  holding  the  button  down,  drag  the 
cursor  to  the  diagonally  opposite  comer  of  the  rectangle.  Release  the  mouse  button. 

In  the  control  panel,  the  Fill  field  to  the  right  of  the  rectangle  indicates  the  current  rectan¬ 
gle  fill  pattern.  Any  rectangles  you  paint  on  the  canvas  will  be  filled  with  this  pattern. 

circle  Draw  a  circle.  To  draw  a  circle  on  the  canvas,  point  to  the  center  of  the  circle,  and  press 
and  hold  the  left  mouse  button.  While  holding  the  button  down,  drag  the  cursor  to  the 
desired  edge  of  the  circle.  Release  the  mouse  button. 

In  the  control  panel,  the  Fill  field  to  the  right  of  the  circle  indicates  the  current  circle  fill 
pattern.  Any  circles  you  paint  on  the  canvas  will  be  filled  with  this  pattern. 

abc  Insert  text.  To  insert  text,  move  the  painting  hand  to  abc  and  type  the  desired  text.  Then 
move  the  cursor  to  the  canvas  and  press  and  hold  the  left  mouse  button.  A  box  will 
appear  where  the  text  is  to  go.  Position  the  box  as  desired  and  release  the  mouse  button. 

In  addition,  you  can  choose  the  font  in  which  to  draw  the  text.  Point  at  the  Fill  field  to 
the  right  of  the  abc  and  either  click  the  left  mouse  button  to  cycle  through  the  available 
fonts  or  press  and  hold  the  right  mouse  button  to  bring  up  a  menu  of  fonts. 

Load  This  is  the  rasterop  to  be  used  when  loading  a  file  in  from  disk.  (See  the  Pixrect  Reference 
Manual  for  details  on  rasterops). 

Fill  This  is  the  rasterop  to  be  used  when  filling  the  canvas.  The  source  for  this  operation  is  the  rectan¬ 
gle  fill  pattern,  and  the  destination  is  the  canvas. 

Proof  This  is  the  rasterop  to  be  used  when  rendering  the  proof  image.  The  source  for  this  operation  is 
the  proof  image,  and  the  destination  is  the  proof  background. 

Proof  background 

The  proof  background  can  be  changed  to  allow  you  to  preview  how  the  image  will  appear  against 
a  variety  of  patterns.  The  squares  just  above  the  proof  area  show  the  patterns  available  for  use  as 
the  proof  background  pattern.  To  change  the  proof  background,  point  at  the  desired  pattern  and 
click  the  left  mouse  button. 
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ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  iconedit.  On  entry  to  iconedit,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC_defauIt.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  oveiride  the  current 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  “C”  locale. 

SEE  ALSO 

sunview(l) 

Pixrect  R^erence  Manual 
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NAME 

id  “  print  the  user  name  and  ID,  and  group  name  and  ID 

SYNOPSIS 

id 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

id  displays  your  user  and  group  ID,  and  your  username.  If  your  real  and  effective  IDs  do  not  match,  both 
are  printed. 

SEE  ALSO 

getuid(2V) 
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NAME 

indent  -  indent  and  format  a  C  program  source  file 
SYNOPSIS 

indent  input-file  [  output-file  ]  [  [  -bap  I  -nbap  ]  [  -bacc  I  -nbacc  ]  [  -bad  I  -nbad  ]  [  -bbb  I  -nbbb  ] 
[  -be  I  -nbc  ]  [  -bl  ]  [  -br  ]  [  -bs  I  -nbs  ]  [  -cw  ]  [  -edn  ]  [  -cdb  I  -nedb  ]  [  -ce  I  -nee  ]  [  -cin  ] 
[-Clin]  [-dn]  [-din]  [-eeil-neei]  [-fcll-nfcl]  [-in]  [-ipl-nip]  [-In]  [-Icn] 
[-Ip  I -nip]  [-pcsl-npcs]  [-npro]  [-psll-npsl]  [-scl-nsc]  [-sobl-nsob]  [-st] 
[  -troff  ]  [  -V  I  -nv  ] 

DESCRIPTION 

indent  is  a  C  program  formatter.  It  reformats  the  C  program  in  the  input-file  according  to  the  switches. 
The  switches  which  can  be  specified  are  described  below.  They  may  appear  before  or  after  the  file  names. 

Note:  if  you  only  specify  an  input-file,  the  formatting  is  done  “in-place”,  that  is,  the  formatted  file  is  written 
back  into  input-file  and  a  backup  copy  of  input-file  is  written  in  the  current  directory.  If  input-file  is  named 
/blah/blah/file,  the  backup  file  is  named  file.  BAK. 

If  output-file  is  specified,  indent  checks  to  make  sure  it  is  different  from  input-file. 

OPTIONS 

The  options  listed  below  control  the  formatting  style  imposed  by  indent. 

-bap,-nbap  If  -bap  is  specified,  a  blank  line  is  forced  after  every  procedure  body.  Default:  -nbap. 

—bacc, -nbacc  If  -bacc  is  specified,  a  blank  line  is  forced  around  every  conditional  compilation  block. 

That  is.  in  front  of  every  #ifdef  and  after  every  #endif.  Other  blanklines  surrounding 
these  will  be  swallowed.  Default:  -nbacc. 

— bad,-nbad  If  -bad  is  specified,  a  blank  line  is  forced  after  every  block  of  declarations.  Default: 

-nbad. 

—bbb,— nbbb  If  -bbb  is  specified,  a  blank  line  is  forced  before  every  block  comment.  Default: 

-nbbb. 


-bc,~nbc 


-brr-bl 


If  -be  is  specified,  then  a  NEWLINE  is  forced  after  each  comma  in  a  declaration,  -nbc 
turns  off  this  option.  The  default  is  -be. 

Specifying  -bl  lines  up  compound  statements  like  this: 

{ 


Specifying  -br  (the  default)  makes  them  look  like  this: 


if  (...){ 


-bs,“nbs 

Enable  (disable)  the  forcing  of  a  blank  after  sizeof.  Some  people  believe  that  sizeof  should  appear 
as  though  it  were  a  procedure  call  (-nbs,  the  default)  and  some  people  believe  that  since  sizeof  is 
an  operator,  it  should  always  be  treated  that  way  and  should  always  have  a  blank  after  it. 


-cn  The  column  in  which  comments  on  code  start  The  default  is  33. 


-edn  The  column  in  which  comments  on  declarations  start  The  default  is  for  these  comments  to  start 
in  the  same  column  as  those  on  code. 
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-cdb,”ncdb 

Enable  (disable)  the  placement  of  comment  delimiters  on  blank  lines.  With  this  option  enabled, 
comments  look  like  this: 

/* 

*  this  is  a  comment 
*/ 

Rather  than  like  this: 

/*  this  is  a  comment  */ 

This  only  affects  block  comments,  not  comments  to  the  right  of  code.  The  default  is  -cdb . 

-ce,-nce 

Enables  (disables)  forcing  else’s  to  cuddle  up  to  the  immediately  preceding  *}’.  The  default  is 
-ce. 

-cin  Sets  the  continuation  indent  to  be  n.  Continuation  lines  will  be  indented  that  far  from  the  begin¬ 
ning  of  the  first  line  of  the  statement.  Parenthesized  expressions  have  extra  indentation  added  to 
indicate  the  nesting,  unless  -Ip  is  in  effect,  -ci  defaults  to  the  same  value  as  -i. 

“din  Cause  case  labels  to  be  indented  n  tab  stops  to  the  right  of  the  containing  switch  statement.  -cliO.5 
causes  case  labels  to  be  indented  half  a  tab  stop.  The  default  is  -cliO  . 

-drt  Control  the  placement  of  comments  which  are  not  to  the  right  of  code.  The  default  -dl  means 
that  such  comments  are  placed  one  indentation  level  to  the  left  of  code.  Specifying  -dO  lines  up 
these  comments  with  the  code.  See  the  section  on  comment  indentation  below. 

-Ain  Specify  the  indentation,  in  character  positions,  from  a  declaration  keyword  to  the  following 
identifier.  The  default  is  -dil6  * 

-eei,“neei 

If  -eei  is  specified,  and  extra  expression  indent  is  applied  on  continuation  lines  of  the  expression 
part  of  if( )  and  while( ).  These  continuation  lines  will  be  indented  one  extra  level  —  twice  instead 
of  just  once.  This  is  to  avoid  the  confusion  between  the  continued  expression  and  the  statement 
that  follows  the  if()  or  while().  Default:  -neei. 

-fcl,-nfcl 

Enables  (disables)  the  formatting  of  comments  that  start  in  column  1.  Often,  comments  whose 
leading  V’  is  in  column  1  have  been  carefully  hand  formatted  by  the  programmer.  In  such  cases, 
-nfcl  should  be  used.  The  default  is  -fcl. 

-in  The  number  of  spaces  for  one  indentation  level.  The  default  is  4. 

-ip, -nip 

Enables  (disables)  the  indentation  of  parameter  declarations  from  the  left  margin.  The  default  is 
-ip. 

-In  Maximum  length  of  an  output  line  with  a  trailing  comment.  The  default  is  78. 

-Yen  Sets  the  line  length  for  block  comments  to  n.  It  defaults  to  being  the  same  as  the  usual  line  length 

as  specified  with  -I. 

-Ip, -nip 

Lines  up  code  surrounded  by  parenthesis  in  continuation  lines.  If  a  line  has  a  left  paren  which  is 
not  closed  on  that  line,  then  continuation  lines  will  be  lined  up  to  start  at  the  character  position  just 
after  the  left  parenthesis.  For  example,  here  is  how  a  piece  of  continued  code  looks  with  -nip  in 
effect: 


pi  =  first_procedure(secondjprocedure(p2,  p3), 
third_procedure(p4,  p5)); 
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With  -Ip  in  effect  (the  default)  the  code  looks  somewhat  clearer: 

pi  =  first_procedure(second_procedure(p2,  p3), 
third_procedure(p4,  p5)); 

Inserting  a  couple  more  NEWLINE  characters  we  get: 

pi  =  first_procedure(second_procedure(p2, 

P3), 

third_procedure(p4, 

p5)); 

-npro  Ignore  the  profile  files, .  /.indentpro  and  7.indent.pro, 

-pcs ,  -npcs 

If  true  (-pcs)  all  procedure  calls  will  have  a  space  inserted  between  the  name  and  the  ’(’.  The 
default  is  -npcs. 

-psl ,  -npsl 

If  true  (-psl)  the  names  of  procedures  being  defined  are  placed  in  column  1  —  their  types,  if  any, 
will  be  left  on  the  previous  lines.  The  default  is  -psl. 

-sc,-nsc 

Enables  (disables)  the  placement  of  asterisks  (‘+*8)  at  the  left  edge  of  all  comments. 

-sob,-nsob 

If  -sob  is  specified,  indent  will  swallow  optional  blank  lines.  You  can  use  this  to  get  rid  of  blank 
lines  after  declarations.  The  default  is  -nsob. 

-St  indent  takes  its  input  from  the  standard  input,  and  put  its  output  to  the  standard  output. 

-T  typename 

Add  typename  to  the  list  of  type  keywords.  Names  accumulate:  -T  can  be  specified  more  than 
once.  You  need  to  specify  all  the  typenames  that  appear  in  your  program  that  are  defined  by 
typedefs  —  nothing  will  be  harmed  if  you  miss  a  few,  but  the  program  won’t  be  formatted  as 
nicely  as  it  should.  This  sounds  like  a  painful  thing  to  have  to  do,  but  it  is  really  a  symptom  of  a 
problem  in  C:  typedef  causes  a  syntactic  change  in  the  language  and  indent  cannot  find  all 
typedefs. 

-troff  Causes  indent  to  format  the  program  for  processing  by  troff.  It  will  produce  a  fancy  listing  in 
much  the  same  spirit  as  vgrind.  If  the  output  file  is  not  specified,  the  default  is  the  standard  out¬ 
put,  rather  than  formatting  in  place.  The  usual  way  to  get  a  troffed  listing  is  with  the  command 

indent -troff  programs  |  troff  -mindent 

-v,-nv  “V  turns  on  “verbose”  mode,  -nv  turns  it  off.  When  in  verbose  mode,  indent  reports  when  it 
splits  one  line  of  input  into  two  or  more  lines  of  output,  and  gives  some  size  statistics  at  comple¬ 
tion.  The  default  is  -nv. 

FURTHER  DESCRIPTION 

You  may  set  up  your  own  “profile”  of  defaults  to  indent  by  creating  a  file  called  .indent.pro  in  either  your 
login  directory  or  the  current  directory  and  including  whatever  switches  you  like.  An  .indenLpro  in  the 
current  directory  takes  precedence  over  the  one  in  your  login  directory.  If  indent  is  run  and  a  profile  file 
exists,  then  it  is  read  to  set  up  the  program’s  defaults.  Switches  on  the  command  line,  though,  always  over¬ 
ride  profile  switches.  The  switches  should  be  separated  by  SPACE,  TAB,  or  NEWLINE  characters. 

Comments 

Boxed  indent  assumes  that  any  comment  with  a  dash  or  star  immediately  after  the  start  of  com¬ 

ment  (that  is,  V*“’orV**’)  is  a  comment  surrounded  by  a  box  of  stars.  Each  line  of  such 
a  comment  is  left  unchanged,  except  that  its  indentation  may  be  adjusted  to  account  for 
the  change  in  indentation  of  the  first  line  of  the  comment. 
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Straight  text  All  other  comments  are  treated  as  straight  text,  indent  fits  as  many  words  (separated  by 
SPACE,  TAB,  or  NEWLINE  characters)  on  a  line  as  possible.  Blank  lines  break  para¬ 
graphs. 

Comment  indentation 

If  a  comment  is  on  a  line  with  code  it  is  started  in  the  “comment  column”,  which  is  set  by  the  -cn  com¬ 
mand  line  parameter.  Otherwise,  the  comment  is  started  at  n  indentation  levels  less  than  where  code  is 
currently  being  placed,  where  n  is  specified  by  the  -dn  command  line  parameter.  If  the  code  on  a  line 
extends  past  the  comment  column,  the  comment  starts  further  to  the  right,  and  the  right  margin  may  be 
automatically  extended  in  extreme  cases. 

Preprocessor  lines 

In  general,  indent  leaves  preprocessor  lines  alone.  The  only  reformatting  that  it  will  do  is  to  straighten  up 
trailing  comments.  It  leaves  imbedded  comments  alone.  Conditional  compilation  (#ifdef...#endif)  is 
recognized  and  indent  attempts  to  correctly  compensate  for  the  syntactic  peculiarities  introduced. 

C  syntax 

indent  understands  a  substantial  amount  about  the  syntax  of  C,  but  it  has  a  “forgiving”  parser.  It  attempts 
to  cope  with  the  usual  sorts  of  incomplete  and  misformed  syntax.  In  particular,  the  use  of  macros  like: 

#define  forever  for(;;) 

is  handled  properly. 

FILES 

./.indent.pro  profile  file 

“/.indent.pro  profile  file 

/usr/share/lib/tmac/tmac.indent 

troff  macro  package  for  ‘indent -troff’  output. 

SEE  ALSO 

Is(lV).  troff(l) 

BUGS 

indent  has  even  more  switches  than  ls(l  V). 

A  common  mistake  that  often  causes  grief  is  typing: 
indent  *.c 

to  the  shell  in  an  attempt  to  indent  all  the  C  programs  in  a  directory.  This  is  probably  a  bug,  not  a  feature. 
The  -bs  option  splits  an  excessively  fine  hair. 
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NAME 

indxbib  -  create  an  inverted  index  to  a  bibliographic  database 
SYNOPSIS 

indxbib  database-file ... 

AVAILABILITY 

pis  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

indxbib  makes  an  inverted  index  to  the  named  database-file  (which  must  reside  within  the  current  direc¬ 
tory),  typically  for  use  by  lookbib(l)  and  refer(l).  A  database  contains  bibliographic  references  (or  other 
kinds  of  information)  separated  by  blank  lines. 

A  bibliographic  reference  is  a  set  of  lines,  constituting  fields  of  bibliographic  information.  Each  field  starts 
on  a  line  beginning  with  a  ‘  followed  by  a  key-letter,  then  a  blank,  and  finally  the  contents  of  the  field, 
which  may  continue  until  the  next  line  starting  with 

indxbib  is  a  shell  script  that  calls  two  programs:  /usr/lib/refer/mkey  and  /usr/lib/refer/inv.  mkey  trun¬ 
cates  words  to  6  characters,  and  maps  upper  case  to  lower  case.  It  also  discards  words  shorter  than  3  char¬ 
acters,  words  among  the  100  most  common  English  words,  and  numbers  (dates)  <  1900  or  >  2000.  These 
parameters  can  be  changed.  See  refer  in  Formatting  Documents  for  details. 

indxbib  creates  an  entry  file  (with  a  .ia  suffix),  a  posting  file  (ab),  and  a  tag  file  (.ic),  in  the  working  direc¬ 
tory. 

FILES 

/usr/lib/refer/mkey 
/usr/lib/refer/inv 
x.ia 
xab 
xAc 
XAg 

SEE  ALSO 

addbib(l),  lookbib(l),  refer(l),  roffbib(l),  sortbib(l) 

Formatting  Documents 

BUGS 

All  dates  should  probably  be  indexed,  since  many  disciplines  refer  to  literature  written  in  the  1800s  or  ear¬ 
lier. 

indxbib  does  not  recognize  pathnames. 


entry  file 
posting  file 
tag  file 
reference  file 
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NAME 

inline  -  in-line  procedure  call  expander 
SYNOPSIS 

/usr/lib/inline  [  -w ]  [ -v  ]  [  -o  outputfile  ]  [  -i inlinefile  ] . . .  [  cpu~option  ]  [fpu-option  ]  filename. . . 
DESCRIPTION 

inline  expands  assembly  language  calls  in  the  indicated  source  files  into  copies  of  the  corresponding  pro¬ 
cedure  bodies  obtained  from  an  inlinefile  specified  with  the  -i  option.  If  no  inlinefile  is  specified,  the 
source  files  are  simply  concatenated  and  written  to  the  standard  output.  If  no  source  files  are  specified,  the 
input  is  read  from  the  standard  input. 

Inline  itself  is  little  more  than  a  sed  script.  Almost  all  of  the  benefit  produced  is  derived  from  subsequent 
peephole  optimization. 

OPTIONS 

-w  Display  warnings  for  duplicate  definitions  on  the  standard  error. 

-V  Verbose.  Display  the  names  of  routines  that  were  actually  in-line  expanded  in  the  sourcefile  on 
the  standard  error. 

-o  outpulfile 

write  output  to  the  indicated  file;  standard  output  by  default. 

-i  inlinefile 

Read  in-line  code  templates  from  inlinefile. 
cpu-option 

Specify  templates  for  the  machine  architecture  of  a  Sun-2  or  Sun-3  system.  If  this  option  is  omit¬ 
ted,  the  proper  template  for  the  host  architecture  is  used.  Can  be  one  of: 

-mcdSOlO  expand  .mc68010  code  templates 
”mc68020  expand  .mc68020  code  templates 

fpu-option 

Specify  a  floating-point  processor  option  for  a  Sun-2  or  Sun-3  system.  Can  be  one  of: 

-fsoft  expand  .fsoft  code  templates  (the  default) 

-fswitch  expand  .fswitch  code  templates 

-fsky  expand  .fsky  code  templates  (-mc68010  only) 

-f68881  expand  .f68881  code  templates  (-mc68020  only) 

-ffpa  expand  .ffpa  code  templates  (-inc68020  only) 

USAGE 

Each  inlinefile  contains  one  or  more  labeled  assembly  language  templates  of  the  form; 
inline-directive 

instructions 

.end 

where  the  instructions,  constitute  an  in-line  expansion  of  the  named  routine.  An  inline-directive  is  a  com¬ 
mand  of  the  form: 

.inline  identifier  ^  argsize 

This  declares  a  block  of  code  for  the  routine  named  by  identifier,  with  argsize  bytes  of  arguments,  (argsize 
is  optional  on  Sun-4  systems).  Calls  to  the  named  routine  are  replaced  by  the  code  in  the  in-line  template. 
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For  Sun-2  and  Sun-3  systems,  the  following  additional  forms  are  recognized: 

.mc68010 

identifier,  argsize 

.mc68020 

identifier,  argsize 

.fsoft 

identifier,  argsize 

.fswitch 

identifier,  argsize 

.fsky 

identifier,  argsize 

.f68881 

identifier,  argsize 

.ffpa 

identifier,  argsize 

These  forms  are  similar  to  .inline,  with  the  addition  of  a  CPU  or  FPU  specification.  The  template  is  only 
expanded  if  the  specified  target  system  matches  the  value  of  the  target  CPU  or  FPU  type,  as  determined  by 
the  command-line  options,  or  if  none  were  given,  by  the  type  of  the  host  system. 

Multiple  templates  are  permitted;  matching  templates  after  the  first  are  ignored.  Duplicate  templates  may 
be  placed  in  order  of  decreasing  performance  of  the  corresponding  hardware;  thus  the  most  efficient  usable 
version  will  be  selected. 

Coding  Conventions  for  all  Sun  Systems 

In-line  templates  should  be  coded  as  expansions  of  C-compatible  procedure  calls,  with  the  difference  that 
the  return  address  cannot  be  depended  upon  to  be  in  the  expected  place,  since  no  call  instruction  will  have 
been  executed.  See  FILES,  below,  for  examples. 

In-line  templates  must  conform  to  standard  Sun  parameter  passing  and  register  usage  conventions,  as 
detailed  below.  They  must  not  call  routines  that  violate  these  conventions;  for  example,  assembly  language 
routines  such  as  setjmp(3  V)  may  cause  problems. 

Registers  other  than  the  ones  mentioned  below  must  not  be  used  or  set. 

Branch  instructions  in  an  in-line  template  may  only  transfer  to  numeric  labels  (If,  2b,  and  so  on)  defined 
within  the  in-line  template.  No  other  control  transfers  are  allowed. 

Only  opcodes  and  addressing  modes  generated  by  Sun  compilers  are  guaranteed  to  work.  Binary  encod¬ 
ings  of  instructions  are  not  supported. 

Coding  Conventions  for  Sun-2  and  Sun-3 

Arguments  are  passed  in  32-bit  aligned  memory  locations  starting  at  sp@.  Note  that  there  is  no  return 
address  on  the  stack,  since  no  jbsr  instruction  will  have  been  executed. 

Results  are  returned  in  dO  or  dO/dl. 

The  following  registers  may  be  used  as  temporaries;  registers  aO,  al,  dO,  and  dl  on  the  MC68010  and 
MC68020;  registers  fpO  and  fpl  on  the  MC68881;  registers  fpaO  through  fpa3  on  the  Sun  Floating-Point 
Accelerator.  No  other  registers  may  be  used. 

The  template  must  delete  exactly  argsize  bytes  from  the  stack.  This  is  to  enable  inline  to  deal  with  autoin¬ 
crement  and  autodecrement  addressing  modes,  which  in  turn  are  used  by  c2  to  delimit  the  lifetimes  of  stack 
temporaries. 

The  stack  must  not  underflow  the  level  of  the  last  argument. 

Use  \cc  branch  mnemonics  instead  of  bcc.  The  hcc  ops  are  span  limited  and  will  fail  if  retargeted  to  a 
label  whose  span  overflows  the  branch  displacement  field. 

Coding  Conventions  for  Sun-4  Systems 

Arguments  are  passed  in  registers  %o0-%o5,  followed  by  memory  locations  starting  at  [%sp+0x5c].  %sp 
is  guaranteed  to  be  64-bit  aligned.  The  contents  of  %o7  are  undefined,  since  no  call  instruction  will  have 
been  executed. 

Results  are  returned  in  %o0  or 

Registers  %o0-%o5  and  %f0-%f31  may  be  used  as  temporaries. 
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Integral  and  single-precision  floating-point  arguments  are  32-bit  aligned. 

Double-precision  floating-point  arguments  are  guaranteed  to  be  64-bit  aligned  if  their  offsets  are  multiples 
of  8. 

Each  control-transfer  instruction  (branches  and  calls)  must  be  immediately  followed  by  a  nop. 

Call  instructions  must  include  an  extra  (final)  argument  which  indicates  the  number  of  registers  used  to 
pass  parameters  to  the  called  routine. 

Note  that  for  Sun-4  systems,  the  instruction  following  an  expanded  ’call’  is  inserted  by  inline  before  the 
expanded  code  to  preserve  the  semantics  of  the  call’s  delay  slot 

FILES 

/usrAib/inline 
/nsr/lib/fsoft/libniJl 
/usr/lib/fs  witch/libm  jl 
/usr/lib/fsky/libm  .il 
/usr/Iib/f68881/libni.il 
/usr/lib/fTpa/libm.il 

WARNING 

inline  does  not  check  for  violations  of  the  coding  conventions  described  above. 


in-line  procedure  call  expander 

in-line  templates  for  software  floating  point  (Sun-2  and  Sun-3  only) 
in-line  templates  for  switched  floating  point  (Sun-2  and  Sun-3  only) 
in-line  templates  for  Sky  FFP  (Sun-2  only) 
in-line  templates  for  Motorola  68881  (Sun-3  only) 
in-line  templates  for  Sun  FPA  (Sun-3  only) 


!  I 

w 
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NAME 

input_from_defaults,  defaults^fromjnput  -  update  the  cunent  state  of  the  mouse  and  keyboard  from  the 
defaults  database,  and  vice  versa 

SYNOPSIS 

input_from_defaults 

defaults_froin_input 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’ s  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

input_froin_defaults  updates  various  parameters  controlling  mouse-  and  keyboard-processing  on  the 
machine  on  which  it  is  run.  It  should  be  used  on  systems  which  are  running  the  SunView  window  system. 
The  parameters  control  the  distribution  of  function  keys  on  the  keyboard,  the  assignment  of  buttons  on  the 
mouse,  the  scaling  of  mouse-to-cursor  motion,  and  the  effect  of  two  filters  on  mouse-motion  originally  pro¬ 
vided  to  compensate  for  defective  mice.  The  new  values  are  taken  from  the  defaults  database,  starting  with 
the  file  .defaults  in  the  user’s  home  directory.  When  Private^only  is  False  in  the  $HOME/.defaults  file, 
the  /usr/lib/defaults/*.d  file  is  consulted.  See  defaultseditcf)  for  more  information  about  the  defaults 
database. 

defauIts_fromJnput  is  the  inverse  operation  to  input_from_defaults.  It  updates  the  user’s  private 
defaults  database  (used  by  defaultsedit(l))  to  reflect  the  current  state  of  kernel  input  parameters  listed 
above. 

FILES 

$HOME/.defaults 
/usr/lib/defaults/*  .d 
$HOME/,login 

SEE  ALSO 

csh(l),  defaultsedit(l) 

SunView  User’s  Guide 

NOTES 

The  parameter  settings  set  by  input_from_defaults  are  lost  when  the  system  goes  down.  To  set  them 
automatically  on  login,  csh(l)  users  can  include  the  following  in  their  .login  files: 

if  (‘tty‘==/dev/console)  then 

echo  ’Setting  input  defaults’ 
input__from_defaults 

endif 

BUGS 

input_from_defaults  should  be  targetable  to  any  user’s  .defaults  file. 
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NAME 

install  -  install  files 
SYNOPSIS 

install  [  -cs  ]  [  -g  group  ]  [  -m  mode  ]  [  -o  owner  ]filel  file2 
install  [  -cs  ]  [  — g  group  ]  [  -m  mode  ]  [  -o  owner  ]  file  . . .  directory 
install  ~d  [  -g  group  ]  [  -m  mode  ]  [  -o  owner  ]  directory 
AVAILABILITY 

This  command  is  available  with  the  Install  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

Install  is  used  within  makefiles  to  copy  new  versions  of  files  into  a  destination  directory  and  to  create  the 
destination  directory  itself. 

The  first  two  forms  are  similar  to  the  cp(l)  command  with  the  addition  that  executable  files  can  be  stripped 
during  the  copy  and  the  owner,  group,  and  mode  of  the  installed  file(s)  can  be  given. 

The  third  form  can  be  used  to  create  a  destination  directory  with  the  required  owner,  group  and  f^rmis- 
sions. 

Note:  install  uses  no  special  privileges  to  copy  files  from  one  place  to  another.  The  implications  of  this 
are: 


OPTIONS 

-g  group 

-m  mode 

-o  owner 

-c 

-s 

-d 


SEE  ALSO 

chgrp(l),  chmod(lV),  cp(l),  mkdir(l),  strip(l),  chown(8) 


You  must  have  permission  to  read  the  files  to  be  installed. 

You  must  have  permission  to  copy  into  the  destination  file  or  directory. 

You  must  have  permission  to  change  the  modes  on  the  final  copy  of  the  file  if  you  want  to  use 
the  ~m  option  to  change  modes. 

You  must  be  superuser  if  you  want  to  specify  the  ownership  of  the  installed  file  with  -o.  If 
you  are  not  the  super-user,  or  if  -o  is  not  in  effect,  the  installed  file  will  be  owned  by  you, 
regardless  of  who  owns  the  original. 

Set  the  group  ownership  of  the  installed  file  or  directory,  (staff  by  default) 

Set  the  mode  for  the  installed  file  or  directory.  (0755  by  default) 

If  run  as  root,  set  the  ownership  of  the  installed  file  to  the  user-ID  of  owner. 

Copy  files.  In  fact  install  always  copies  files,  but  the  -c  option  is  retained  for  back¬ 
wards  compatibility  with  old  shell  scripts  that  might  otherwise  break. 

Strip  executable  files  after  they  are  copied. 

Create  a  directory.  Missing  parent  directories  are  created  as  required  as  in  mkdir  -p.  If 
the  directory  already  exists,  the  owner,  group  and  mode  will  be  set  to  the  values  given 
on  the  command  line. 
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NAME 

ipcrm  -  remove  a  message  queue»  semaphore  set,  or  shared  memory  ID 

SYNOPSIS 

ipcrm  [  primitives  ] 

DESCRIPTION 

ipcrm  removes  one  or  several  messages,  semaphores,  or  shared  memory  identifiers,  as  specified  by  the  fol¬ 
lowing  primitives: 

-q  msqid 

removes  the  message  queue  identifier  msqid  from  the  system  and  destroys  the  message  queue  and 
data  structures  associated  with  it. 

-m  shmid 

removes  the  shared  memory  identifier  shmid  from  the  system.  The  shared  memory  segment  and 
data  structures  associated  with  it  are  destroyed  after  the  last  detach. 

-s  semid 

removes  the  semaphore  identifier  semid  from  the  system  and  destroys  the  set  of  semaphores  and 
data  structures  associated  with  it. 

-Q  msgkey 

removes  the  message  queue  identifier,  created  widi  key  msgkey ,  from  the  system  and  destroys  the 
message  queue  and  data  structures  associated  with  it. 

-M  shmkey 

removes  the  shared  memory  identifier,  created  with  key  shmkey^  from  the  system.  The  shared 
memory  segment  and  data  structures  associated  wiUi  it  are  destroyed  after  the  last  detach. 

-S  semkey 

removes  the  semaphore  identifier,  created  with  key  semkey,  from  the  system  and  destroys  the  set 
of  semaphores  and  data  structures  associated  with  it. 

The  identifiers  and  keys  may  be  found  by  using  ipcs(l). 

The  details  of  removing  identifiers  are  described  in  msgctl(2),  shmctl(2),  and  semctl(2)  in  the  sections 
detailing  the  IPC  RMID  command. 

SEE  ALSO 

ipcs(l),  msgctl(2),  msgget(2),  seinctl(2),  semget(2),  semop(2),  shmctl(2),  shmget(2),  shmop(2) 
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NAME 

ipcs  -  report  interprocess  communication  facilities  status 


SYNOPSIS 

ipcs  [  primitives  ] 


DESCRIPTION 

ipcs  prints  information  about  active  interprocess  communication  facilities  as  specified  by  the  primitives 
shown  below.  If  no  primitives  are  given,  information  is  printed  in  short  format  for  message  queues,  shared 
memory,  and  semaphores  that  are  currently  active  in  the  system. 

Command  —  Line  Primitives 

If  any  of  the  primitives  -m,  -q,  or  ~s  are  specified,  information  about  only  indicated  facilities  is  printed.  If 
none  of  these  are  specified,  information  about  all  three  is  printed. 


-q 


-s 

-b 


Print  information  about  active  message  queues. 

Print  information  about  active  shared  memory  segments. 

Print  information  about  active  semaphores. 

Print  the  currently  allowed  size  information.  (Maximum  number  of  bytes  in  messages 
on  queue  for  message  queues,  size  of  segments  for  shared  memory,  and  number  of 
semaphores  in  each  set  for  semaphores.)  See  below  for  the  meaning  of  columns  in  a 
listing. 


-c  Print  creator’s  login  name  and  group  name.  See  below. 

“O  Print  information  on  outstanding  usage.  (Number  of  messages  on  queue  and  total 

number  of  bytes  in  messages  on  queue  for  message  queues  and  number  of  processes 
attached  to  shared  memory  segments.) 

~P  Print  process  number  information.  (Process  ID  of  last  process  to  send  a  message  and 

process  ID  of  last  process  to  receive  a  message  on  message  queues  and  process  ID  of 
creating  process  and  process  ID  of  last  process  to  attach  or  detach  on  shared  memory 
segments)See  below. 


-t  Print  time  information.  (Time  of  the  last  control  operation  that  changed  the  access  per¬ 

missions  for  all  facilities.  Time  of  last  msgsnd  and  last  msgrcv  (see  msgop(2))  on  mes¬ 
sage  queues,  last  shmat  and  last  shmdt  (see  shmop(2))  on  shared  memory,  last 
semop(2)  on  semaphores.)  See  below. 


-a  Use  all  display  primitives.  (This  is  a  shorthand  notation  for  -b,  -c,  -o,  -p,  and  -t.) 

-C  corefile  Use  the  file  corefile  in  place  of  /dev/mem. 


— N  namelist  The  argument  will  be  taken  as  the  name  of  an  alternate  filenamelist  (/vmunix  is  the 

default). 


The  column  headings  and  the  meaning  of  the  columns  in  an  ipcs  listing  are  given  below;  the  letters  in 
parentheses  indicate  the  primitives  that  cause  the  corresponding  heading  to  appear;  all  means  that  the  head¬ 
ing  always  appears.  Note:  these  primitives  only  determine  what  information  is  provided  for  each  facility; 
they  do  not  determine  which  facilities  will  be  listed. 


T 


ID 


(all)  Type  of  the  facility: 

q  message  queue 

m  shared  memory  segment 

s  semaphore 

(all)  The  identifier  for  the  facility  entry. 
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KEY  (all) 


MODE  (all) 


OWNER 

(all) 

GROUP 

(all) 

CREATOR 

(a,c) 

CGROUP 

(a,c) 

GBYTES 

(a,o) 

QNUM 

(a,o) 

QBYTES 

(a,b) 

LSPID 

(a,p) 

LRPID 

(a,p) 

STIME 

(a,t) 

RTIME 

(a,t) 

CTIME 

(a.t) 

NATTCH 

(a,o) 

SEGSZ 

(a,b) 

CPID 

(a,p) 

LPID 

(a,p) 

ATIME 

(a,t) 

The  key  used  as  an  argument  to  msgget(2),  semget(2),  or  shmget(2)  to  create  the  facil¬ 
ity  entry.  (Note:  The  key  of  a  shared  memory  segment  is  changed  to  IPC^PRIVATE 
when  the  segment  has  been  removed  until  all  processes  attached  to  the  segment  detach 
it.) 

The  facility  access  modes  and  flags:  The  mode  consists  of  1 1  characters  that  are  inter¬ 
preted  as  follows: 

The  first  two  characters  are: 

R  If  a  process  is  waiting  on  a  msgrcv. 

S  If  a  process  is  waiting  on  a  msgsnd. 

D  If  the  associated  shared  memory  segment  has  been  removed.  It  will 
disappear  when  the  last  process  attached  to  the  segment  detaches  it. 

C  If  the  associated  shared  memory  segment  is  to  be  cleared  when  the  first 
attach  is  executed. 

-  If  the  corresponding  special  flag  is  not  set. 

The  next  9  characters  are  interpreted  as  three  sets  of  three  bits  each.  The  first 
set  refers  to  the  owner’s  permissions;  the  next  to  permissions  of  others  in  the 
user-group  of  the  facility  entry;  and  the  last  to  all  others.  Within  each  set,  the 
first  character  indicates  permission  to  read,  the  second  character  indicates  per¬ 
mission  to  write  or  alter  the  facility  entry,  and  the  last  character  is  currently 
unused. 

The  permissions  are  indicated  as  follows: 
r  If  read  permission  is  granted, 
w  If  write  permission  is  granted, 
a  If  alter  permission  is  granted. 

—  If  the  indicated  permission  is  not  granted. 

The  login  name  of  the  owner  of  the  facility  entry. 

The  group  name  of  the  group  of  the  owner  of  the  facility  entry. 

The  login  name  of  the  creator  of  the  facility  entry. 

The  group  name  of  the  group  of  the  creator  of  the  facility  entry. 

The  number  of  bytes  in  messages  currently  outstanding  on  the  associated  message 
queue. 

The  number  of  messages  currently  outstanding  on  the  associated  message  queue. 

The  maximum  number  of  bytes  allowed  in  messages  outstanding  on  the  associated 
message  queue. 

The  process  ID  of  the  last  process  to  send  a  message  to  the  associated  queue. 

The  process  ID  of  the  last  process  to  receive  a  message  from  the  associated  queue. 

The  time  the  last  message  was  sent  to  the  associated  queue. 

The  time  the  last  message  was  received  from  the  associated  queue. 

The  time  when  the  associated  entry  was  created  or  changed. 

The  number  of  processes  attached  to  the  associated  shared  memory  segment. 

The  size  of  the  associated  shared  memory  segment. 

The  process  ID  of  the  creator  of  the  shared  memory  entry. 

The  process  ID  of  the  last  process  to  attach  or  detach  the  shared  memory  segment. 

The  time  the  last  attach  was  completed  to  the  associated  shared  memory  segment. 
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(a,t)  The  time  the  Iasi  detach  was  completed  on  the  associated  shared  memory  segment. 

(a,b)  The  number  of  semaphores  in  the  set  associated  with  the  semaphore  entry. 

(a,t)  The  time  the  last  semaphore  operation  was  completed  on  the  set  associated  with  the 
semaphore  entry. 

system  namelist 
/dev/mem  memory 

/etc/passwd  user  names 

/etc/group  group  names 

SEE  ALSO 

ipcrm(l),  msgop(2),  semctl(2),  semget(2),  semop(2),  shmctl(2).  shmget(2),  shmop(2) 

BUGS 

Things  can  change  while  ipcs  is  running;  the  picture  it  gives  is  only  a  close  approximation  to  reality. 


DTIME 

NSEMS 

OTnVIE 

FILES 

/vmunix 
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NAME 

join  -  relational  database  operator 
SYNOPSIS 

join  [ -an  ]  [  -e  string  ]  [  -J  [112]  m][~o  list ]  [ -tc  ]  filenamel  filename2 

DESCRIPTION 

Join  forms,  on  the  standard  output,  a  join  of  the  two  relations  specified  by  the  lines  of  filenamel  and 
filename2.  If  filenamel  is  *-*,  the  standard  input  is  used. 

filenamel  and  filename2  must  be  sorted  in  increasing  ASCII  collating  sequence  on  the  fields  on  which  they 
are  to  be  joined  —  normally  the  first  in  each  line. 

There  is  one  line  in  the  output  for  each  pair  of  lines  in  filenamel  and  filename2  that  have  identical  join 
fields.  The  output  line  normally  consists  of  the  common  field,  then  the  rest  of  the  line  from  filenamel ,  then 
the  rest  of  the  line  from  filename2. 

The  default  input  field  separators  are  SPACE,  TAB,  and  NEWLINE  characters.  If  the  default  input  field 
separators  are  used,  multiple  separators  count  as  one  field  separator,  and  leading  separators  are  ignored. 
The  default  output  field  separator  is  a  blank. 

OPTIONS 

-an  The  parameter  n  can  be  one  of  the  values: 

1  Produce  a  line  for  each  unpairable  line  in  filenamel . 

2  Produce  a  line  for  each  unpairable  line  in  filename2 . 

3  Produce  a  line  for  each  unpairable  line  in  both  filenamel  and  filename2 . 

The  normal  output  is  also  produced. 

-e  string 

Replace  empty  output  fields  by  string. 

The  J  may  be  immediately  followed  by  n,  which  is  either  a  1  or  a  2.  If  n  is  missing,  the  join  is  on 
the  m’th  field  of  both  files.  If  n  is  present,  the  join  is  on  the  mTh  field  of  file  n ,  and  the  first  field 
of  the  other.  Note:  join  counts  fields  from  1  instead  of  0  as  sort(lV)  does. 

-0  list  Each  output  line  comprises  the  fields  specified  in  list,  each  element  of  which  has  the  form  njn, 
where  n  is  a  file  number  and  m  is  a  field  number.  The  common  field  is  not  printed  unless 
specifically  requested.  Note:  join  counts  fields  from  1  instead  of  0  like  sort  does. 

-tc  Use  character  c  as  a  separator  (tab  character).  Every  appearance  of  c  in  a  line  is  significant.  The 
character  c  is  used  as  the  field  separator  for  both  input  and  output. 

EXAMPLE 

The  following  command  line  will  join  the  password  file  and  the  group  file,  matching  on  the  numeric  group 
ID,  and  outputting  the  login  name,  the  group  name  and  the  login  directory.  It  is  assumed  that  the  files  have 
been  sorted  in  ASCII  collating  sequence  on  the  group  ID  fields, 

join  -jl  4  -j2  3  -o  1.1 2.1 1.6  -t:  /etc/passwd  /etc/group 

SEE  ALSO 

awk(l),  comm(l),  look(l),  sort(lV),  uniq(l) 

BUGS 

With  default  field  separation,  the  collating  sequence  is  that  of  sort  -b;  with  -t,  the  sequence  is  that  of  a 
plain  sort. 

The  conventions  of  join,  sort,  comm,  uniq,  look,  and  awk  are  wildly  incongruous. 

Filenames  that  are  numeric  may  cause  conflict  when  the  -o  option  is  used  right  before  listing  filen^es. 
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NAME 

keylogin  -  decrypt  and  store  secret  key 

SYNOPSIS 

keylogin 

DESCRIPTION 

keylogin  prompts  the  user  for  their  login  password,  and  uses  it  to  decrypt  the  user’s  secret  key  stored  in  the 
publickey(5)  database.  Once  decrypted,  the  user’s  key  is  stored  by  the  local  key  server  process 
keyserv(8C)  to  be  used  by  any  secure  network  services,  such  as  NFS. 

Normally,  login(l)  does  this  work  when  the  user  logs  onto  the  system,  but  running  keylogin  may  be  neces¬ 
sary  if  the  user  did  not  type  a  password  to  login(l). 

SEE  ALSO 

chkey(l),  login(l),  publickey(5),  keyserv(8C),  newkey(8) 
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NAME 

keylogout  -  delete  stored  secret  key 

SYNOPSIS 

keylogout  [  -f  ] 

DESCRIPTION 

keylogout  deletes  the  key  stored  by  the  key  server  process  keyserv(8C)  to  be  used  by  any  secure  network 
services,  such  as  NFS.  Further  access  to  the  key  is  revoked,  however  current  session  keys  may  remain  valid 
till  they  expire,  or  are  refreshed.  This  option  will  cause  any  background  jobs  that  need  secure  RPC  services 
to  fail,  and  any  scheduled  at  jobs  that  need  the  key  to  fail.  Also  since  only  one  copy  is  kept  on  a  machine 
of  the  key,  it  is  a  bad  idea  to  place  this  in  your  .logout  file  since  it  will  affect  other  sessions  on  the  same 
machine. 

OPTIONS 

~f  Forget  the  rootkey.  This  will  break  secure  NFS  if  it  is  done  on  a  server. 

SEE  ALSO 

chkey(l),  login(l),  keylogin(l),  publickey(5),  keyserv(8C),  newkey(8) 
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NAME 

kill  -  send  a  signal  to  a  process,  or  terminate  a  process 
SYNOPSIS 

kill  [  -signal  ]  pid , , . 

kill-l 

DESCRIPTION 

kill  sends  the  TERM  (terminate,  15)  signal  to  the  processes  with  the  specified  pids.  If  a  signal  name  or 
number  preceded  by  is  given  as  first  argument,  that  signal  is  sent  instead  of  terminate.  The  signal 
names  are  listed  by  using  the  -1  option,  and  are  as  given  in  <signaLh>,  stripped  of  the  common  SIG  prefix. 

The  terminate  signal  will  kill  processes  that  do  not  catch  the  signal,  so  ‘kill  -9  . . is  a  sure  kill,  as  the 
KILL  (9)  signal  cannot  be  caught.  By  convention,  if  process  number  0  is  specified,  all  members  in  the  pro¬ 
cess  group  (that  is,  processes  resulting  from  the  current  login)  are  signaled  (but  beware:  this  works  only  if 
you  use  sh(l);  not  if  you  use  csh(l).)  Negative  process  numbers  also  have  special  meanings;  see  kiIl(2V) 
for  details.  The  killed  processes  must  belong  to  the  current  user  unless  he  is  the  super-user. 

To  shut  the  system  down  and  bring  it  up  single  user  the  super-user  may  send  the  initialization  process  a 
TERM  (terminate)  signal  by  ‘kill  1’;  see  init(8).  To  force  init  to  close  and  open  terminals  according  to 
what  is  currently  in  /etc/ttytab  use  ‘kill  —HUP  V  (sending  a  hangup  signal  to  process  1). 

The  sheU  reports  the  process  number  of  an  asynchronous  process  started  with  '&’  (run  in  the  background). 
Process  numbers  can  also  be  found  by  using  ps(l). 

kill  is  built  in  to  csh(l);  it  allows  job  specifiers,  such  as  ‘kill  %  . .  in  place  of  kill  arguments.  See 
csh(l)  for  details. 

OPTIONS 

-1  Display  a  list  of  signal  names, 

FILES 

/etc/ttytab 
SEE  ALSO 

csh(l),  ps(l),  kill(2V),  sigvec(2),  init(8) 

BUGS 

A  replacement  for  ‘kill  0’  for  csh(l)  users  should  be  provided. 
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NAME 

last  -  indicate  last  logins  by  user  or  terminal 
SYNOPSIS 

last  [ -number  ][ -f filename  ]  [  name. ..  ] 

DESCRIPTION 

last  looks  back  in  the  wtmp  file  which  records  aU  logins  and  logouts  for  information  about  a  user,  a  tele¬ 
type  or  any  group  of  users  and  teletypes.  Arguments  specify  names  of  users  or  teletypes  of  interest 
Names  of  teletypes  may  be  given  fully  or  abbreviated.  For  example  last  0  is  the  same  as  lastftyO.  If  multi¬ 
ple  arguments  are  given,  the  information  which  applies  to  any  of  the  arguments  is  printed.  For  example 
last  root  console  would  list  all  of  **root*s”  sessions  as  well  as  all  sessions  on  the  console  terminal,  last 
displays  the  sessions  of  the  specified  users  and  teletypes,  most  recent  first,  indicating  the  times  at  which  the 
session  began,  the  duration  of  the  session,  and  the  teletype  which  the  session  took  place  on.  If  the  session 
is  still  continuing  or  was  cut  short  by  a  reboot,  last  so  indicates. 

The  pseudo-user  reboot  logs  in  at  reboots  of  the  system,  thus 

last  reboot 

will  give  an  indication  of  mean  time  between  reboot. 

last  with  no  arguments  displays  a  record  of  all  logins  and  logouts,  in  reverse  order. 

If  last  is  intemipted,  it  indicates  how  far  the  search  has  progressed  in  wtmp.  If  interrupted  with  a  quit  sig¬ 
nal  (generated  by  a  CTRL-\)  last  indicates  how  far  the  search  has  progressed  so  far,  and  the  search  contin¬ 
ues. 


OPTIONS 

-number 

limit  the  number  of  entries  displayed  to  that  specified  by  number. 

-f  filename 

Use  filename  as  the  name  of  the  accounting  file  instead  of  /var/adm/wtmp. 

FILES 

/var/adm/wtmp  login  data  base 

SEE  ALSO 

lastcomm(l),  utmp(5V),  ac(8) 
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NAME 

lastcomm  -  show  the  last  commands  executed,  in  reverse  order 
SYNOPSIS 

lastcomm  [  command-name  ] . . .  [  user-name  ] . . .  [  terminal-name  ]... 

DESCRIPTION 

lastcomm  gives  infoimation  on  previously  executed  commands,  lastcomm  with  no  arguments  displays 
informadon  about  all  the  commands  recorded  during  the  current  accounting  file’s  lifedme.  If  called  with 
arguments,  lastcomm  displays  only  accounting  entries  with  a  matching  command-name,  user-name  or 
terminal-name.  ’ 

EXAMPLES 

The  command 

example%  lastcomm  a.out  root  ttydO 

would  produce  a  listing  of  all  the  executions  of  commands  named  a.out,  by  user  root  while  using  the  ter¬ 
minal  ttydO. 

example  %  lastcomm  root 

would  produce  a  listing  of  all  the  commands  executed  by  user  root. 

For  each  process  entry,  lastcomm  displays  the  following  information: 

•  The  command  name  under  which  the  process  was  called. 

•  One  or  more  flags  indicating  special  information  about  the  process.  The  flags  have  the  follow¬ 
ing  meanings: 

F  The  process  performed  a  fork  but  not  an  exec. 

S  The  process  ran  as  a  set-user-id  program. 

0  The  process  dumped  memory. 

X  The  process  was  killed  by  some  signal. 

•  The  name  of  the  user  who  ran  the  process. 

•  The  terminal  from  which  the  user  was  logged  in  at  the  time  (if  applicable). 

•  The  amount  of  CPU  time  used  by  the  process  (in  seconds). 

•  The  date  and  time  the  process  starts. 

FILES 

/var/adm/pacct  accounting  file 

SEE  ALSO 

last(l),  sigvec(2),  acct(5),  core(5) 
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NAME 

Id,  ld.so  -  link  editor,  dynamic  link  editor 
SYNOPSIS 

Id  [  -align  datum  ]  [  -assert  assertion-keyword  ]  [  -A  name  ]  [  -^binding-keyword  ]  [  -d  ] 

[-dc]  [-dp]  [-Y>hex]  [-sentry]  [-lx]  [-Ldir]  [-M]  [-n]  [-N]  [-oname]  [-p] 
[“r][-s][-S][-t][-T[text]  to][-Tdatata][-uname][-x][-X][-y5y?n] 

[— z  ] filename  ... 

DESCRIPTION 

Id  combines  object  programs  to  create  an  executable  file  or  another  object  program  suitable  for  further  Id 
processing  (with  the  -r  option).  The  object  modules  on  which  Id  operates  are  specified  on  the  command 
line,  and  can  be: 

•  simple  object  files,  which  typically  end  in  the  .0  suffix,  and  are  referred  to  as  **dot-oh”  files 

•  ar(l  V)  library  archives  (^),  or  “libraries” 

•  dynamically-bound,  sharable  object  files  (.so),  are  also  referred  to  as  “shared  libraries,”  which 
are  created  from  previous  Id  executions. 

Unless  an  output  file  is  specified,  Id  produces  a  file  named  a.out.  This  file  contains  the  object  files  given  as 
input,  appropriately  combined  to  form  an  executable  file. 

OPTIONS 

When  linking  debugging  or  profiling  objects,  include  the  -g  or  -pg  option  (see  cc(lV)),  as  appropriate,  in 
the  Id  command. 


Options  should  appear  before  filenames,  except  for  abbreviated  library  names  specified  with  -I  options, 
and  some  binding  control  options  specified  by  -B  (which  can  appear  anywhere  in  the  line). 

-align  datum 

Force  the  global  uninitialized  data  symbol  datum  (usually  a  FORTRAN  common  block)  to  be 
page-aligned.  Increase  its  size  to  a  whole  number  of  pages,  and  place  its  first  byte  at  the  start  of  a 
page. 

-assert  assertion-keyword 

Check  an  assertion  about  the  link  editing  being  performed.  The  assertion  desired  is  specified  by 
the  assertion-keyword  string.  Id  is  silent  if  the  assertion  holds,  else  it  yields  a  diagnostic  and 
aborts.  Valid  assertion-keyword's  and  their  interpretations  are: 


definitions 

nodefinitions 

nosyntbolic 

pure-text 


If  the  resulting  program  were  run  now,  there  would  be  no  run-time 
undefined  symbol  diagnostics.  This  assertion  is  set  by  default. 

Permit  the  successful  linking  of  a  program  with  unresolved  references. 

There  are  no  symbolic  relocation  items  remaining  10  be  resolved. 

The  resulting  load  has  no  relocation  items  remaining  in  its  text. 


-A  name 

Incremental  loading:  linking  is  to  be  done  in  a  manner  so  that  the  resulting  object  may  be  read  into 
an  already  executing  program,  name  is  the  name  of  a  file  whose  symbol  table  is  taken  as  a  basis  on 
which  to  define  additional  symbols.  Only  newly  linked  material  is  entered  into  the  text  and  data 
portions  of  a.out,  but  the  new  symbol  table  will  reflect  all  symbols  defined  before  and  after  the 
incremental  load.  This  argument  must  appear  before  any  other  object  file  in  the  aigument  list. 
One  or  both  of  the  -T  options  may  be  used  as  well,  and  will  be  taken  to  mean  that  the  newly 
linked  segment  will  commence  at  the  corresponding  addresses  (which  must  be  a  multiple  of  the 
page  size).  The  default  value  is  the  old  value  of  _end. 
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-'^binding-keyword 

Specify  allowed  binding  times  for  the  items  which  follow.  Allowed  values  of  binding-keyword 
are: 

dynamic  Allow  dynamic  binding:  do  not  resolve  symbolic  references,  allow  creation  of 

run-time  symbol  and  relocation  environment.  -Bdynamic  is  the  default.  When 
— Bdynamic  is  in  effect,  all  sharable  objects  encountered  until  a  succeeding 
-Bstatic  may  be  added  dynamically  to  the  object  being  linked.  Non-sharable 
objects  are  bound  statically. 

nosymbolic  Do  not  perform  symbolic  relocation,  even  if  other  options  imply  it. 

static  Bind  statically.  Opposite  of  -Bdynamic.  Implied  when  either  -n  or  ~N  is 

specified.  Influences  handling  of  all  objects  following  its  specification  on  a 
command  line  until  the  next  -Bdynamic. 

symbolic  Force  symbolic  relocation.  Normally  implied  if  an  entry  point  has  been 

specified  with  -e,  or  if  dynamic  loading  is  in  effect. 

-d  Force  common  storage  for  uninitialized  variables  and  other  common  symbols  to  be  allocated  in 
the  current  Id  run,  even  when  the  -r  flag  is  present  (which  would  otherwise  postpone  this  binding 
until  the  final  linking  phase). 

-dc  Do  -d,  but  also  copy  initialized  data  referenced  by  this  program  from  shared  objects. 

-dp  Force  an  alias  definition  of  undefined  procedure  entry  points.  Used  with  dynamic  binding  to 
improve  sharing  and  the  locality  of  run-time  relocations. 

-D  hex  Pad  the  data  segment  with  zero-valued  bytes  to  make  it  hex  bytes  long. 

~e  entry 

Define  the  entry  point:  the  entry  argument  is  made  the  name  of  the  entry  point  of  the  loaded  pro¬ 
gram.  Implies -Bsymbolic. 

”lx[.v]  This  option  is  an  abbreviation  for  the  library  name  ]ib;c.a,  where  ;c  is  a  string.  Id  searches  for 
libraries  first  in  any  directories  specified  with  -L  options,  then  in  the  standard  directories  /lib, 
/usr/lib,  and  /usr/local/lib.  A  library  is  searched  when  its  name  is  encountered,  so  the  placement 
of  a  -I  is  significant.  If  a  dynamically  loadable  object  is  found,  and  -Bdynamic  is  in  effect  at  that 
point  on  the  command  line,  then  Id  prepares  to  access  the  object  for  relocation  at  run-time.  In 
such  a  case,  the  optional  .v  suffix  can  be  used  to  indicate  a  specific  library  version. 

~Ldir  Add  dir  to  the  list  of  directories  in  which  to  search  for  libraries.  Directories  specified  with  -L  are 
searched  before  the  standard  directories,  /lib,  /usr/lib,  and  /usr/local/lib.  When  building  a  pro¬ 
gram  in  which  one  or  more  objects  are  loaded  when  -Bdynamic  is  in  effect,  those  directories 
specified  by  -L  options  will  be  “remembered”  for  use  at  execution  time.  This  permits  the  con¬ 
struction  of  software  that  uses  shared  objects  as  libraries  not  residing  in  the  standard  locations  and 
avoids  requiring  the  specification  of  the  LD_LIBRARY_PATH  environment  variable  in  order  to 
execute  such  software.  Note  that  such  directories  are  retained  in  exactly  the  form  specified  in  the 
option,  which  means  that  relative  directory  specifications  (i.e.,  not  beginning  with  “/”)  will  be 
evaluated  relative  to  the  current  directory  when  the  program  is  run,  not  just  during  the  operation 
of  Id. 

-M  Produce  a  primitive  load  map,  listing  the  names  of  the  files  which  will  be  loaded. 

-n  Arrange  (by  giving  the  output  file  a  0410  “magic  number”)  that  when  the  output  file  is  executed, 

the  text  portion  will  be  read-only  with  the  data  areas  placed  at  the  beginning  of  the  next  address 
boundary  following  the  end  of  the  text.  Implies  -Bstatic. 

-N  Do  not  make  the  text  portion  read-only.  (Use  “magic  number”  0407.)  Implies  —Bstatic. 

-o  name 

name  is  made  the  name  of  the  Id  output  file,  instead  of  a.out. 


Sun  Release  4.1 


Last  change:  21  January  1990 


259 


LD(1) 


USER  COMMANDS 


LD(1) 


-p  Arrange  for  the  data  segment  to  begin  on  a  page  boundary,  even  if  the  text  is  not  shared  (with  the 
-N  option). 

-r  Generate  relocation  bits  in  the  output  file  so  that  it  can  be  the  subject  of  another  Id  run.  This  flag 
also  prevents  final  definitions  from  being  given  to  common  symbols,  and  suppresses  the 
“undefined  symbol”  diagnostics. 

-s  Strip  the  output,  that  is,  remove  the  symbol  table  and  relocation  bits  to  save  space  (but  impair  the 
usefulness  of  the  debuggers).  This  information  can  also  be  removed  by  strip(l). 

-S  Strip  the  output  by  removing  all  symbols  except  locals  and  globals. 

~t  Trace:  display  the  name  of  each  file  as  it  is  processed. 

“T  [  text  ]  hex 

Start  the  text  segment  at  location  hex.  Specifying  -T  is  the  same  as  using  the  -Ttext  option. 
-Tdata  hex 

Start  the  data  segment  at  location  hex.  This  option  is  only  of  use  to  programmers  wishing  to  write 
code  for  PROMs,  since  the  resulting  code  cannot  be  executed  by  the  system. 

-u  name 

Enter  name  as  an  undefined  symbol.  This  is  useful  for  loading  wholly  from  a  library,  since  ini- 
tially  the  symbol  table  is  empty  and  an  unresolved  reference  is  needed  to  force  the  loading  of  the 
first  routine. 

-X  Preserve  only  global  (non-.globl)  symbols  in  the  output  symbol  table;  only  enter  external  symbols. 
This  option  saves  some  space  in  the  output  file. 

-X  Record  local  symbols,  except  for  those  whose  names  begin  with  L.  This  option  is  used  by  cc  to 
discard  internally  generated  labels  while  retaining  symbols  local  to  routines. 

-^sym  Display  each  file  in  which  sym  appears,  its  type  and  whether  the  file  defines  or  references  it. 
Many  such  options  may  be  given  to  trace  many  symbols.  It  is  usually  necessary  to  begin  sym  with 
an  as  external  C,  FORTRAN  and  Pascal  variables  begin  with  underscores. 

-z  Arrange  for  the  process  demand  paged  from  the  resulting  executable  file  (0413  “magic  number”). 
This  is  the  default.  Results  in  a  (32-byte)  header  on  the  output  file  followed  by  text  and  data  seg¬ 
ments,  each  of  which  has  a  multiple  of  page-size  bytes  (being  padded  out  with  null  characters  in 
the  file  if  necessary).  With  this  format  the  ^^t  few  BSS  segment  symbols  may  actually  end  up  in 
the  data  segment;  this  is  to  avoid  wastii^g  the  space  resulting  from  rounding  the  data  segment  size. 
Implies  -Bdynamic. 

USAGE 

Command  Line  Processing 

In  general,  options  should  appear  ahead  of  the  list  of  files  to  process.  Unless  otherwise  specified,  the  effect 
of  an  option  covers  all  of  Id  operations,  independent  of  that  option’s  placement  on  the  command  line. 
Exceptions  to  this  rule  include  some  of  the  binding  control  options  specified  by  ‘-B’  and  the  abbreviated 
library -names  specified  by  ‘-1’.  These  may  appear  anywhere,  and  their  influence  is  dependent  upon  their 
location.  Some  options  may  be  obtained  from  environment  variables,  such  options  are  interpreted  before 
any  on  the  command  line  (see  ENVIRONMENT,  below). 

Object  File  Processing 

The  files  specified  on  the  command  line  are  processed  in  the  order  listed.  Information  is  extracted  from 
each  file,  and  concatenated  to  form  the  output.  The  specific  processing  performed  on  a  given  file  depends 
upon  whether  it  is  a  simple  object  file,  a  library  archive,  or  a  shared  library. 

Simple  object  (.0)  files  are  concatenated  to  the  output  as  they  are  encountered. 

Library  archive  (.a)  files  are  searched  exactly  once  each,  as  each  is  encountered;  only  those  archive  entries 
matching  an  unresolved  external  reference  are  extracted  and  concatenated  to  the  output.  If  a  member  of  an 
archive  references  a  symbol  defined  by  another  member  of  that  same  archive,  the  member  making  the 
reference  must  appear  before  the  member  containing  the  definition. 
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On  Sun386i,  a  library  contains  a  dictionary  of  symbols,  On  other  Sun  systems,  processing  library  archives 
through  ranlib(l)  provides  this  dictionary.  In  addition,  you  can  use  lorder(l),  in  combination  with 
tsort(l)  to  place  library  members  in  calHng  order  (see  lorder(l)  for  details),  or  both  (for  fastest  symbol 
lookup).  The  first  member  of  an  archived  processed  by  ranlib  has  the  reserved  name  of  .SYMDEF, 
which  Id  takes  to  be  the  dictionary  of  all  symbols  defined  by  members  of  the  archive. 

Sharable  objects  (.so)  are  scanned  for  symbol  definitions  and  references,  but  are  not  normally  included  in 
the  output  from  Id,  except  in  cases  where  a  shared  library  exports  initialized  data  structures  and  the  — dc 
option  is  in  effect.  However,  the  occurrence  of  each  sharable  object  file  in  the  Id  command  line  is  noted  in 
the  resulting  executable  file;  this  notation  is  utilized  by  an  execution-time  variant  of  Id,  ld.so,  for  deferred 
and  dynamic  loading  and  binding  during  execution.  See  Execution-Time  Loading,  below,  for  details. 

The  -I  option  specifies  a  short  name  for  an  pbject  file  or  archive  used  as  a  library.  The  full  name  of  the 
object  file  is  derived  by  adding  the  prefix  lib  and  a  suffix  of  either  .a  or  .so[.v]  to  indicate  an  ar(lV) 
archive  or  a  shared  library,  respectively.  The  specific  suffix  used  is  determined  through  rules  discussed  in 
Binding  and  Relocation  Semantics,  below. 

Id  searches  for  the  desired  object  file  through  a  list  of  directories  specified  by  -L  options,  the  environment 
variable  LD_LIBRARY_PATH,  and  finally,  the  built-in  list  of  standard  library  directories:  /lib,  /usr/lib,  and 
/usr/local/lib. 

Binding  and  Relocation  Semantics 

The  manner  in  which  Id  processes  a  given  object  file  is  dependent  in  part  upon  the  “binding  mode”  in 
which  it  is  operating  at  the  lime  the  file  is  encountered.  This  binding  mode  is  specified  by  the  -B  flag, 
which  takes  the  keyword  arguments: 

dynamic  Allow  dynamic  binding,  do  not  resolve  symbolic  references,  and  allow  creation  of 
execution-time  symbol  and  relocation  information.  This  is  the  default  setting. 

static  Force  static  binding,  implied  by  options  that  generate  non-sharable  executable  for¬ 
mats. 

-Bdynamic  and  -Bstatic  may  be  specified  several  times,  and  may  be  used  to  toggle  each  other  on  and  off. 
Like  -I,  the  influence  of  each  depends  upon  its  location  within  the  command  line.  When  -Bdynamic  is  in 
effect,  -1  searches  may  be  satisfied  by  the  first  occurrence  of  either  form  of  library  (.so  or  .a),  but  if  both 
are  encountered,  the  .so  form  is  preferred.  When  —Bstatic  is  in  effect.  Id  refuses  to  use  any  .so  libraries  it 
encounters;  it  continue  searching  for  the  .a  form.  Furthermore,  an  explicit  request  to  load  a  .so  file  is 
treated  as  an  error. 

After  Id  has  processed  all  input  files  and  command  line  options,  the  form  of  the  output  it  produces  is  based 
on  the  information  provided  in  both.  Id  first  tries  to  reduce  all  symbolic  references  to  relative  numerical 
offsets  within  the  executable  it  is  building.  To  perform  this  “symbolic  reduction,”  Id  must  be  able  to  deter¬ 
mine  that; 

•  all  information  relating  to  the  program  has  been  provided,  in  particular,  no  .so  is  to  be  added  at 
execution  time;  and/or 

•  the  program  has  an  entry  point,  and  symbolic  reduction  can  be  performed  for  all  symbols  hav¬ 
ing  definitions  existing  in  the  material  provided. 

It  should  be  noted  that  uninitialized  “common”  areas  (for  example,  uninitialized  C  globals)  are  allocated  by 
the  link  editor  after  it  has  collected  all  references.  In  particular,  this  allocation  can  not  occur  in  a  program 
that  still  requires  the  addition  of  information  contained  in  a  .so  file,  as  the  missing  information  may  affect 
the  allocation  process.  Initialized  “commons”  however,  are  allocated  within  the  executable  in  which  their 
definition  appears. 

After  Id  has  performed  all  the  symbolic  reductions  it  can,  it  attempts  to  transform  all  relative  references  to 
absolute  addresses.  Id  is  able  to  perform  this  “relative  reduction”  only  if  it  has  been  provided  some  abso¬ 
lute  address,  either  implicitly  through  the  specification  of  an  entry  point,  or  explicitly  through  Id 
command-line  options.  If,  after  performing  all  the  reductions  it  can,  there  are  no  further  relocations  or 
definitions  to  perform,  then  Id  has  produced  a  completely  linked  executable. 
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Execution-Time  Loading 

In  the  event  that  one  or  more  reductions  can  not  be  completed,  the  executable  will  require  further  link  edit¬ 
ing  at  execution  time  in  order  to  be  usable.  Such  executables  contain  an  data  structure  identified  with  the 
symbol _ ^DYNAMIC.  An  incompletely  linked  **main”  program  should  be  linked  with  a  “bootstrap”  rou¬ 
tine  that  invokes  ld,so,  which  uses  the  information  contained  in  the  main  program’s _ DYNAMIC  to 

assemble  the  rest  of  the  executables  constituting  the  entire  program.  A  standard  Sun  compilation  driver 
(such  as  cc(lV))  automatically  includes  such  a  module  in  each  “main”  executable. 

When  ld.so  is  given  control  on  program  startup,  it  finds  all  .so  files  specified  when  the  program  was  con¬ 
structed  (and  all  .so’s  on  which  they  depend),  and  loads  them  into  the  address  space.  The  algorithm  by 
which  such  files  are  found  mimics  that  used  when  Id  is  run,  and  like  Id,  can  be  influenced  by  the  setting  of 
LD_LIBRARY_PATH  and  any  -L  options  specified  to  Id  when  the  program  was  built.  ld.so  then  com¬ 
pletes  all  remaining  relocations,  with  the  exception  of  procedure  call  relocations;  failure  to  resolve  a  given 
non-procedural  relocation  results  in  termination  of  the  program  with  an  appropriate  diagnostic. 

Procedure  relocations  are  resolved  when  the  referencing  instruction  is  first  executed.  It  should  be  noted 
that  it  is  possible  for  “undefined  symbol”  diagnostics  to  be  produced  during  program  execution  if  a  given 
target  is  not  defined  when  referenced. 

Although  it  is  possible  for  binding  errors  to  occur  at  execution-time,  such  an  occurrence  generally  indicates 
something  wrong  in  the  maintenance  of  shared  objects.  Id’s  -assert  nodefinitions  function  (on  by 
default)  checks  at  Id-time  whether  or  not  an  execution-time  binding  error  would  occur. 

Version  Handling  for  Shared  Libraries 

To  allow  the  independent  evolution  of  .so’s  used  as  libraries  and  the  programs  which  use  them,  Id’s  han¬ 
dling  of  .so  files  found  through  -1  options  involves  the  retention  and  management  of  version  control  infor¬ 
mation.  The  .so  files  used  as  such  “shared  libraries”  are  post-fixed  with  a  Dewey-decimal  format  string 
describing  the  version  of  the  “library”  contained  in  the  file. 

The  first  decimal  component  is  called  the  library’s  “major  version”  number,  and  the  second  component  its 
“minor  version”  number.  When  Id  records  a  .so  used  as  a  library,  it  also  records  these  two  numbers  in  the 
database  used  by  Id.so  at  execution  time.  In  turn,  ld.so  uses  these  numbers  to  decide  which  of  multiple  ver¬ 
sions  of  a  given  library  is  “best”  or  whether  any  of  the  available  versions  are  acceptable.  The  rules  are: 

•  Major  Versions  Identical:  the  major  version  used  at  execution  time  must  exactly  match  the 
version  found  at  Id-time.  Failure  to  find  an  instance  of  the  library  with  a  matching  major  ver¬ 
sion  causes  a  diagnostic  to  be  issued  and  the  program’s  execution  to  be  terminated. 

•  Highest  Minor  Version:  in  the  presence  of  multiple  instances  of  libraries  that  match  the 
desired  major  version,  ld.so  uses  the  highest  minor  version  it  finds.  However,  if  the  highest 
minor  version  found  at  execution  time  is  less  than  the  version  found  at  Id-time,  a  warning 
diagnostic  is  issued;  program  execution  continues. 

The  semantics  of  version  numbers  are  such  that  major  version  numbers  should  be  changed  whenever  inter¬ 
faces  are  changed.  Minor  versions  should  be  changed  to  reflect  compatible  updates  to  libraries,  and  pro¬ 
grams  will  silently  favor  the  highest  compatible  version  they  can  obtain. 

Special  Symbols 

A  number  of  symbols  have  special  meanings  to  Id  and  programs  should  not  define  these  symbols.  The 
symbols  described  below  are  those  actually  seen  by  Id.  Note:  C  and  several  other  languages  prepend  sym¬ 
bols  they  use  with  ‘J. 

_etext  The  first  location  after  the  text  of  the  program. 

_edata  The  first  location  after  initialized  data, 
end  The  first  location  after  all  data. 
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__DYNAMIC 

Identifies  an  Id-produced  data  structure.  It  is  defined  with  a  non-zero  value  in  executables  which 
require  ex^ution-time  link  editing.  By  convention,  if  defined,  it  is  the  first  symbol  in  the  symbol 
table  associated  with  an  a.out  file. 

___GLOBAL_OFFSET_TABLE_ 

A  position-independent  reference  to  an  Id-constructed  table  of  addresses.  This  table  is  constructed 
from  “position-independent”  data  references  occurring  in  objects  that  have  been  assembled  with 
the  assembler’s  -k  flag  (invoked  on  behalf  of  C  compilations  performed  with  the  -pic  flag).  A 
related  table  (for  which  no  symbol  is  currently  defined)  contains  a  series  of  transfer  instructions 
and  is  created  from  “position-independent”  procedure  calls  or,  if  —dp  is  specified  to  Id,  a  list  of 
undefined  symbols. 

Symbols  in  object  files  beginning  with  the  letter  L  are  taken  to  be  local  symbols  and  unless  otherwise 
specified  are  purged  from  Id  output  files. 

ENVIRONMENT 

LD_LIBRARY_PATH 

A  colon-separated  list  of  directories  in  which  to  search  for  libraries  specified  with  the  -1  option. 
Similar  to  the  PATH  environment  variable.  LD__LIBRARY__PATH  also  affects  library  searching 
during  execution-time  loading,  causing  the  search  to  use  first  those  directories  found  in  the 
environment  variable,  then  any  directories  specified  by  -L  options,  and  finally  the  standard  direc¬ 
tories  /usr/lib  and  /usr/locaVlib.  NOTE;  when  running  a  set-user-  or  set-group-ID  program,  ld.so 
will  only  search  for  libraries  in  directories  it  “trusts”,  which  are  /usr/lib,  /usr/51ib,  /usr/local/Iib, 
and  any  directories  specified  within  the  executable  as  a  result  of  -L  options  given  when  the  exe¬ 
cutable  was  constructed. 

LD_OPTIONS 

A  default  set  of  options  to  Id.  LD_OPTIONS  is  interpreted  by  Id  just  as  though  its  value  had  been 
placed  on  the  command  line,  immediately  following  the  name  used  to  invoke  Id,  as  in: 

example  %  Id  $LD_OPTIONS  . . .  other-arguments  . . . 

Note:  Environment  variable-names  beginning  with  the  characters  ‘LD_’  are  reserved  for  possible  future 
enhancements  to  Id. 

FILES 

/usr/Iib/Iib*.a 
Iib*.so.v 
Iib*.sa.v 
/usr/lib/ld.so 
/usr/lib/*crt*.o 
a,out 

/usr/local/lib 
SEE  ALSO 

ar(lV),  as(l),  cc(lV),  lorder(l),  ranlib(l),  strip(l),  tsort(l),  ldconfig(8) 

BUGS 

Options  are  being  overloaded  and  are  an  inappropriate  vehicle  for  describing  to  Id  the  wide  variety  of 
things  it  can  do.  There  needs  to  be  a  link-editing  language  which  can  be  used  in  the  more  complex  situa¬ 
tions. 

The  -r  option  does  not  properly  handle  programs  assembled  with  the  -k  (position-independent)  flag, 
invoked  from  cc  with  -pic  or  -PIC. 


libraries 
shared  libraries 

exported,  initialized  shared  library  data 
execution-time  Id 
default  program  bootstraps 
output  file 
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NAME 

Idd  -  list  dynamic  dependencies 

SYNOPSIS 

Idd  filename  . . . 

DESCRIPTION 

For  oSiCYi  filename  ,  Idd  lists  the  dynamically  loaded  objects  on  which  that  filename  depends,  if  any.  If  the 
dynamic  dependency  is  a  “library”  (a  so-called  “shared  library”),  then  both  the  canonical  form  of  the 
library  name  and  version  and  the  actual  pathname  used  to  access  the  library  are  listed.  For  example,  if  a 
given  filename  uses  a  shared  C  library  version  4,  which  has  the  name  /usr/Iib/libc.so.4.9  (where  9  is  the 
most  recent  revision  to  interface  version  number  4)  then  \dd  filename  will  report: 

filename: 

-lc.4  =>  /usr/Iib/libc.so.4.9 

For  each  filename  which  is  not  an  executable  program,  or  else  does  not  require  any  dynamic  objects  for  its 
execution,  Idd  will  issue  an  appropriate  diagnostic. 

It  should  be  noted  that  although  all  dynamically  linked  programs  depend  on  the  file  /usr/lib/ld.so ,  Idd  will 
never  report  this  dependency. 

SEE  ALSO 

ld(l) 
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NAME 

leave  -  remind  you  when  you  have  to  leave 

SYNOPSIS 

leave  [[  +  ]  hhmm  ] 

DESCRIPTION 

leave  sets  an  alarm  to  a  time  you  specify  and  will  tell  you  when  the  time  is  up.  leave  waits  until  the 
specified  time,  then  reminds  you  that  you  have  to  leave.  You  are  reminded  5  minutes  and  1  minute  before 
the  actual  time,  and  at  the  time.  After  the  specified  time,  it  reminds  you  every  minute  thereafter  10  more 
times,  leave  disappears  after  you  log  off. 

You  can  specify  the  time  in  on  of  two  ways,  namely  as  an  absolute  time  of  day  in  the  form  hhmm  where  hh 
is  a  time  in  hours  (on  a  12  or  24  hour  clock),  or  you  can  place  a  +  sign  in  front  of  the  time,  in  which  case 
the  time  is  relative  to  the  current  time,  that  is,  the  specified  number  of  hours  and  minutes  from  now.  All 
times  are  converted  to  a  12  hour  clock,  and  assumed  to  be  in  the  next  12  hours. 

If  no  argument  is  given,  leave  prompts  with  ‘When  do  you  have  to  leave?’,  leave  exits  if  you  just  type  a 
NEWLINE,  otherwise  the  reply  is  assumed  to  be  a  time.  This  form  is  suitable  for  inclusion  in  a  .login  or 
.profile. 

leave  ignores  interrupts,  quits,  and  terminates.  To  get  rid  of  it  you  should  either  log  off  or  use  kill  -9  and 
its  process  ID. 

EXAMPLES 

The  first  example  sets  the  alarm  to  an  absolute  time  of  day: 

example  %  leave  1535 

Alarm  set  for  Wed  Mar  7  15:35:07  1984 

work  work  work  work 

example  %  Time  to  leave! 

The  second  example  sets  the  alarm  for  10  minutes  in  the  future: 
example  %  leave  +10  Alarm  set  for  Wed  Mar  7 

work  work  work  work 

example  %  Time  to  leave! 

work  work  work  work 

example  %  You’re  going  to  be  late! 

FILES 

.login 

.profile 

SEE  ALSO 

calendar(l) 
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NAME 

lex  -  lexical  analysis  program  generator 
SYNOPSIS 

lex  [  -fntv  ]  [filename  ]  . . . 

DESCRIPTION 

lex  generates  programs  to  be  used  in  simple  lexical  analysis  of  text.  Each  filename  (the  standard  input  by 
default)  contains  regular  expressions  to  search  for,  and  actions  written  in  C  to  be  executed  when  expres¬ 
sions  are  found. 

A  C  source  program,  lex,yy.c  is  generated,  to  be  compiled  as  follows: 
cc  lex.yy.c  -U 

This  program,  when  run,  copies  unrecognized  portions  of  the  input  to  the  output,  and  executes  the  associ¬ 
ated  C  action  for  each  regular  expression  that  is  recognized.  The  actual  string  matched  is  left  in  yytext,  an 
external  character  array. 

Matching  is  done  in  order  of  the  strings  in  the  file.  The  strings  may  contain  square  braces  to  indicate  char¬ 
acter  classes,  as  in  [abx— z]  to  indicate  a,  b,  x,  y,  and  z;  and  the  operators  +,  +  and  ?,  which  mean,  respec¬ 
tively,  any  nonnegative  number,  any  positive  number,  or  either  zero  or  one  occurrences  of  the  previous 
character  or  character-class.  The  “dot”  character  (‘ .  ’)  is  the  class  of  all  ASCH  characters  except  NEWLINE. 

Parentheses  for  grouping  and  vertical  bar  for  alternation  are  also  supported.  The  notation  rid^e)  in  a  rule 
indicates  instances  of  regular  expression  r  between  d  and  e.  It  has  a  higher  precedence  than  j,  but  lower 
than  that  of  *,  ?,  +,  or  concatenation.  The  ^  (caiat  character)  at  the  beginning  of  an  expression  permits  a 
successful  match  only  immediately  after  a  NEWLINE,  and  the  $  character  at  the  end  of  an  expression 
requires  a  trailing  NEWLINE. 

The  /  character  in  an  expression  indicates  trailing  context;  only  the  part  of  the  expression  up  to  the  slash  is 
returned  in  yytext,  although  the  remainder  of  the  expression  must  follow  in  the  input  stream. 

An  operator  character  may  be  used  as  an  ordinary  symbol  if  it  is  within  symbols  or  preceded  by  ‘\’. 

Three  subroutines  defined  as  macros  are  expected:  input()  to  read  a  character;  unput(c)  to  replace  a  char¬ 
acter  read;  and  output(c)  to  place  an  output  chaiacter.  They  are  defined  in  terms  of  the  standard  streams, 
but  you  can  override  them.  The  program  generated  is  named  yylex(),  and  the  library  contains  a  mainO 
which  calls  it.  The  action  REJECT  on  the  right  side  of  the  rule  rejects  this  match  and  executes  the  next  suit¬ 
able  match;  the  function  yymore()  accumulates  additional  characters  into  the  same  yytext;  and  the  func¬ 
tion  yyless(n)  where  n  is  the  number  of  characters  to  retain  in  yytext.  The  macros  input  and  output  use 
files  yyin  and  yyout  to  read  from  and  write  to,  defaulted  to  stdin  and  stdout,  respectively. 

In  a  lex  program,  any  line  beginning  with  a  blank  is  assumed  to  contain  only  C  text  and  is  copied;  if  it  pre¬ 
cedes  %%  it  is  copied  into  the  external  definition  area  of  the  lex.yy.c  file.  All  rules  should  follow  a  %  %, 
as  in  YACC.  Lines  preceding  %  %  which  begin  with  a  nonblank  character  define  the  string  on  the  left  to  be 
the  remainder  of  the  line;  it  can  be  used  later  by  surrounding  it  with  {  }.  Note;  curly  brackets  do  not  imply 
parentheses;  only  string  substitution  is  done. 

The  external  names  generated  by  lex  all  begin  with  the  prefix  yy  or  YY. 

Certain  table  sizes  for  the  resulting  finite-state  machine  can  be  set  in  the  definitions  section: 

%p  n  number  of  positions  is  n  (default  2000) 

%n  n  number  of  states  is  n  (500) 

%t  n  number  of  parse  tree  nodes  is  n  (1000) 

%a  n  number  of  transitions  is  n  (3000) 

The  use  of  one  or  more  of  the  above  automatically  implies  the  -v  option,  unless  the  -n  option  is  used. 
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OPTIONS 

-f  Faster  compilation.  Do  not  bother  to  pack  the  resulting  tables;  limited  to  small  programs. 

-n  Opposite  of  -v;  -n  is  default. 

-t  Place  the  result  on  the  standard  output  instead  of  in  file  lex.yy.c. 

-V  Print  a  one-line  summary  of  statistics  of  the  generated  analyzer. 

EXAMPLES 

The  following  command  line: 
lex  lexcommands 

would  draw  lex  instructions  from  the  file  lexcommands,  and  place  the  ou4)ut  in  lex.yy.c. 

The  following: 

%%  [A-Z]  putchar  (yytext[0]+'a -'AO;  [  ]+$  ;  [  ]+  putchar(' '); 

is  an  example  of  a  lex  program.  It  converts  upper  case  to  lower,  removes  blanks  at  the  end  of  lines,  and 
replaces  multiple  blanks  by  single  blanks. 


D 

[0-9] 

%% 

if 

printf("IF  statement\n"); 

[a-z]+ 

printfC’tag,  value  %s\n”,yytext); 

0{D}+ 

printfC octal  number  %s\n",yytext); 

{D}+ 

printf("  decimal  number  %s\n",yytext); 

"++" 

printfC'unary  op\n"); 

printf!"  binary  op\n”); 

{  loop: 

while  (input! )  !=  '*0; 
switch  (input!)) 


{ 

case  7':  break; 
case  unput('+'); 
default:  go  to  loop; 

} 

} 

FILES 

lex.yy.c 

SEE  ALSO 

sed(lV),  yacc(l) 

Programming  Utilities  and  Libraries 

NOTES 

The  lex  command  is  not  changed  to  support  8-bit  symbol  names,  as  this  would  produce  lex  source  code  that 
is  not  portable  between  systems. 
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NAME 

line  -  read  one  line 

SYNOPSIS 

line 

DESCRIPTION 

line  copies  one  line  (up  to  a  NEWLINE)  from  the  standard  input  and  writes  it  on  the  standard  output.  It 
returns  an  exit  code  of  1  on  EOF  and  always  prints  a  NEWLINE  at  least.  It  is  often  used  within  shell  scripts 
to  read  a  line  from  the  terminal, 

SEE  ALSO 

sh(l),  read(2V) 
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NAME 

lint  -  a  C  program  verifier 
SYNOPSIS 

lint  [  -abchinquvxz  ]  [  -Dname  [=def]  ]  [  -\iosi=arch  ]  [  -Wrectory  ]  [  -Mibrary  ]  [  -o  outputfile  ] 

[  — target=arc/i  ]  [  -Vname  ]  filename  . . . 

lint  [  —CUbrary  ]  [  ^Dname  [=def]  ]  [  ~hosi=arch  ]  [  —Idirectory  ]  [  —Mibrary  ]  [  — target=arc/i  ] 

[  -Uname  ]  filename  . . . 

SYSTEM  V  SYNOPSIS 

/usr/5bin/lint  [  -abcghnpquvxzO  ]  [  -Dname  [=d^]  ]  [  -Idirectory  ]  [  -Mibrary  ]  [  -o  outputfile  ] 

[  —\}name  ]  filename  . . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

lint  attempts  to  detect  features  of  the  named  C  program  files  that  are  likely  to  be  bugs,  to  be  non-portable, 
or  to  be  wasteful.  It  also  performs  stricter  type  checking  than  does  the  C  compiler,  lint  runs  the  C  prepro¬ 
cessor  as  its  first  phase,  with  the  preprocessor  symbol  lint  defined  to  allow  certain  questionable  code  to  be 
altered  or  skipped  by  lint.  Therefore,  this  symbol  should  be  thought  of  as  a  reserved  word  for  all  code  that 
is  to  be  checked  by  lint. 

Among  the  possible  problems  that  are  currently  noted  are  unreachable  statements,  loops  not  entered  at  the 
top,  automatic  variables  declared  and  not  used,  and  logical  expressions  with  constant  values.  Function 
calls  are  checked  for  inconsistencies,  such  as  calls  to  functions  that  return  values  in  some  places  and  not  in 
others,  functions  called  with  varying  numbers  of  arguments,  function  calls  that  pass  arguments  of  a  type 
other  than  the  type  the  function  expects  to  receive,  functions  whose  values  are  not  used,  and  calls  to  func¬ 
tions  not  returning  values  that  use  the  non-existent  return  value  of  the  function. 

Filename  arguments  ending  with  .c  are  taken  to  be  C  source  files.  Filename  arguments  with  names  ending 
with  .In  are  taken  to  be  the  result  of  an  earlier  invocation  of  lint,  with  either  the  -i  or  the  -C  option  in 
effect.  The  ,ln  files  are  analogous  to  the  .0  (object)  files  produced  by  the  cc(lV)  from  ,c  files,  lint  also 
accepts  special  libraries  specified  with  the  -1  option,  which  contain  simplified  definitions  of  standard 
library  routines  (preprocessed  by  ‘lint  -C’)  for  faster  checking  of  function  cils. 

lint  processes  the  various  .c,  .In,  and  Uih-MibraryAn  (lint  library)  files  and  process  them  in  command-line 
order.  By  default,  lint  appends  the  standard  C  lint  library  (llib-lc.ln)  to  the  end  of  the  list  of  files.  When 
the  “C  and  -i  options  are  omitted  the  second  pass  of  lint  checks  this  list  of  files  for  mutual  compatibility. 
When  the  -C  or  the  -i  options  are  used,  the  .In  and  the  \lib-\library  An  files  are  ignored. 

SYSTEM  V  DESCRIPTION 

Filename  arguments  with  names  ending  with  .In  are  taken  to  be  the  result  of  an  earlier  invocation  of  lint, 
with  either  the  -c  or  the  -o  option  in  effect. 

lint  processes  the  various  .c,  .In,  and  llib-lfi7?rary,ln  (lint  library)  files  and  process  them  in  command-line 
order.  By  default,  lint  appends  the  standard  C  lint  library  (llib-lc.ln)  to  the  end  of  the  list  of  files.  How¬ 
ever,  if  the  -p  option  is  used,  the  portable  C  lint  library  (llib-port.ln)  is  appended  instead.  When  the  “C 
option  is  omitted  the  second  pass  of  lint  checks  this  list  of  files  for  mutual  compatibility.  When  the  -c 
option  is  used,  the  .In  and  the  llib-l/z^rary.ln  files  are  ignored. 

lint  produces  its  first-pass  output  on  a  per-source-file  basis.  Complaints  regarding  included  files  are  col¬ 
lected  and  printed  after  all  source  files  have  been  processed.  If  the  -c  option  is  not  used,  information  gath¬ 
ered  from  all  input  files  is  then  collected  and  checked  for  consistency.  At  this  point,  if  it  is  not  clear 
whether  a  complaint  stems  from  a  given  source  file  or  from  one  of  its  included  files,  the  source  file  name  is 
printed,  followed  by  a  question  mark. 
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OPTIONS 

-a  Report  assignments  of  long  values  to  variables  that  are  not  long. 

— b  Report  break  statements  that  cannot  be  reached.  This  is  not  the  default  because,  unfortunately, 

most  lex(l)  and  many  yacc(l)  outputs  produce  many  such  complaints. 

-c  Complain  about  casts  which  have  questionable  portability. 

~h  Apply  a  number  of  heuristic  tests  to  attempt  to  intuit  bugs,  improve  style,  and  reduce  waste. 

-i  Produce  a  .In  file  for  every  .c  file  on  the  command  line.  These  .In  files  are  the  product  of  lint’s 

first  pass  only,  and  are  not  checked  for  compatibility  between  functions. 

-n  Do  not  check  compatibility  against  the  standard  library. 

-q  Do  not  complain  about  constructs  that  do  not  cause  portability  problems  between  current  Sun 

implementations  of  the  C  language  but  that  will  cause  portability  problems  between  other  imple¬ 
mentations.  If  the  -q  flag  is  specified,  lint  treats  type  enum  as  an  int,  treats  type  long  as  type  int 
and  type  unsigned  long  as  unsigned  int,  and  treats  a  0  argument  as  being  conformable  with  any 
points. 

-u  Do  not  complain  about  functions  and  external  variables  used  and  not  defined,  or  defined  and  not 
used  (this  is  suitable  for  running  lint  on  a  subset  of  files  comprising  part  of  a  larger  program). 

-V  Suppress  complaints  about  unused  arguments  in  functions. 

-X  Report  variables  referred  to  by  extern  declarations,  but  never  used. 

~z  Do  not  complain  about  structures  that  are  never  defined  (for  example,  using  a  structure  pointer 
without  knowing  its  contents). 

-CUbrary 

Create  a  lint  library  with  the  name  WihAIibrary  An. 

-Dnam€[=^def\ 

Define  name  for  cpp(l),  as  if  by  a  #define  directive.  If  no  definition  is  given,  name  is  defined  as 

1. 

-host=arch  (Sun-2,  Sun-3,  and  Sun-4  systems  only) 

Define  the  host  architecture  to  be  arch.  The  default  is  the  architecture  returned  by  the  arch(l) 
command,  arch  can  be  one  of  sun2,  sun3,  or  sun4. 

-Idirectory 

Add  directory  to  the  list  of  list  of  directories  in  which  to  search  for  include  files.  Include  files  with 
names  that  do  not  begin  with  /  are  always  sought  first  in  the  directory  of  the  filename  argument, 
then  in  directories  named  in  -I  options,  then  in  the  /usr/include  directory. 

-Mibrary 

Use  the  lint  library  library  from  the  /usr/lib/lint  directory. 

-o  outputfile 

Name  the  output  file  outputfile.  outpufile  cannot  be  the  same  as  sourcefile  (lint  will  not  overwrite 
the  source  file). 

--target=arc/i  (Sun-2,  Sun-3,  and  Sun-4  systems  only) 

Define  the  target  architecture  to  be  arch,  for  additional  portability  checks  specific  to  that  architec¬ 
ture.  The  default  is  the  value  returned  by  the  arch(l)  command,  arch  can  be  one  of:  sun2,  sun3, 
or  sun4. 

-Vname 

Remove  any  initial  definition  of  name  for  the  preprocessor. 
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SYSTEM  V  OPTIONS 

The  sense  of  the  -a,  -b,  -h,  and  ~x  options  is  reversed  in  the  System  V  version  of  lint;  the  tests  they  con¬ 
trol  are  performed  unless  the  flag  is  specified.  The  -C  option  is  not  available;  instead,  the  -c  or  -o  options 
can  be  used.  The  -i  option  is  not  used;  instead,  the  -c  option  can  be  used.  The  -q,  -host,  and  -target 
options  are  not  available. 

-c  Produce  a  .In  file  for  every  .c  file  on  the  command  line.  These  .In  files  are  the  product  of  lint’s 
first  pass  only,  and  are  not  checked  for  compatibility  between  functions. 

-g 

“O  These  options  are  accepted  but  ignored.  By  recognizing  these  options,  lint’s  behavior  is  closer  to 
that  of  the  cc(lV)  command. 

-n  Do  not  check  compatibility  against  either  the  standard  or  the  portable  lint  library. 

-p  Attempt  to  check  portability  of  code  to  other  dialects  of  C,  such  as  IBM  370  and  Honeywell  GCOS . 
Along  with  performing  stricter  checking,  this  option  truncates  all  non-external  names  to  eight 
characters,  and  all  external  names  to  six  characters  and  one  case. 

-0  library 

Create  a  lint  library  with  the  name  llib-l/i^.ln.  The  ~c  option  nullifies  any  use  of  the  -o  option. 
The  lint  library  produced  is  the  input  that  is  given  to  lint’s  second  pass.  The  -o  option  simply 
saves  this  file  in  the  named  lint  library.  To  produce  a  llib-l/i^.ln  without  extraneous  messages,  use 
of  the  -X  option  is  suggested.  The  -v  option  is  useful  if  the  source  file(s)  for  the  lint  library  are 
just  external  interfaces  (for  example,  the  way  the  file  Ilib-lc  is  written).  These  option  settings  are 
also  available  through  the  use  of  “lint  comments”  (see  Input  Grammar  below). 

USAGE 

For  more  information  about  lint  refer  to  lint  in  Programming  Utilities  and  Libraries 
To  create  lint  libraries,  use  the  -C  option.  For  example 
example  %  lint  -Ccongress  filenames  . . . 

where  filenames  are  the  C  sources  of  library  congress,  produces  a  file  llib-lcongress.ln  in  the  current  direc- 
tCH7  in  the  correct  library  format  suitable  for  “linting”  programs  using  -Icongress. 

Input  Grammar 

lint’s  first  pass  reads  standard  C  source  files,  lint  recognizes  the  following  C  comments  as  commands. 
/+NOTREACHED+/ 

At  appropriate  points,  inhibit  comments  about  unreachable  code.  (This  comment  is  typically 
placed  just  after  calls  to  functions  like  exit(2V)). 

/♦VARARGSn*/ 

Suppress  the  usual  checking  for  variable  numbers  of  arguments  in  the  following  function  declara¬ 
tion.  The  data  types  of  the  first  n  arguments  are  checked;  a  missing  n  is  taken  to  be  0.  In  this  ver¬ 
sion  of  lint,  /*VARARGS0*/  is  allowed.  It  no  longer  indicates  the  absence  of  variable  arguments. 

/♦ARGSUSED*/ 

Enable  the  -v  option  for  the  next  function. 

/+LINTLIBRARY*/ 

At  the  beginning  of  a  file,  shut  off  complaints  about  unused  functions  and  function  arguments  in 
this  file.  This  is  equivalent  to  using  the  -v  and  -x  options. 
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The  behavior  of  the  -c  and  the  -o  options  allows  for  incremental  use  of  lint  on  a  set  of  C  source  files. 
Invoking  lint  — c  for  each  source  file  produces  a  corresponding  Jn  file,  and  prints  all  messages  pertaining 
to  that  source  file.  After  all  of  the  source  files  have  been  run  through  lint  separately,  it  is  invoked  once 
more  (without  the  — c  option),  and  with  all  of  the  .In  files  and  —lx  options.  This  produces  messages  about 
any  inconsistencies  between  files.  This  scheme  works  well  with  niake(l),  since  it  allows  make  to  “lint” 
only  those  source  files  that  have  been  modified  since  the  last  time  lint  was  run. 

To  create  lint  libraries,  use  the  -o  option.  For  example 

example  %  lint  -x  -o  congress ^/enomes  . . . 

v/heTQ  filenames  are  the  C  sources  of  library  congress,  produces  a  file  llib-lcongress  Jn  in  the  current  direc¬ 
tory  in  the  correct  library  format  suitable  for  “linting”  programs  using  -Icongress. 

EXAMPLE 

The  following  lint  call: 

example  %  lint  -b  rnyfilex 

checks  the  consistency  of  the  code  in  the  C  source  file  file  myfile.c.  The  — b  option  indicates  that  unreach¬ 
able  break  statements  are  to  be  checked  for. 

FILES 

/usr/lib/lint/lint[12]  programs 

/usr/lib/lint/llib-1*  Jn  various  prebuilt  lint  libraries 

/usr/libAint/llib-1*  sources  of  the  prebuilt  lint  libraries 

The  following  lint  libraries  are  supplied  with  SunOS:  -Ic,  -Icore,  -Icurses,  -Ikvm,  -llwp,  -Im,  -Imp, 
-Ipixrect,  -Iplot,  -Isuntool,  -Isunwindow,  -Itermcap.  and  -Itermlib.  Additional  lint  libraries  may  be 
installed  separately. 

SYSTEM  V  FILES 

/usr/51ib/lint/lint[12]  programs 

/usr/51ib/lint/llib-l=^.ln  various  prebuilt  lint  libraries 

/usr/51ib/lint/llib-l*  sources  of  the  prebuilt  lint  libraries 

The  following  System  V  lint  libraries  are  supplied  with  SunOS:  -Ic,  -Icore,  -Icurses,  -Ikvm,  -llwp,  -Im, 
-Imp,  —Ipixrect,  -Iplot,  -Iport.  -Isuntool,  and  -Isunwindow.  Additional  lint  libraries  may  be  installed 
separately. 

SEE  ALSO 

cc(lV),  cpp(l),  lex(l),  make(l),  yacc(l),  exit(2V),  setjmp(3V),  ansic(7V),  bsd(7V),  posix(7V),  sunos(7), 
svidii(7V),  svidiii(7V),  xopen(7V) 

Programming  Utilities  and  Libraries 

NOTES 

Because  cc  does  not  generate  or  support  8-bit  symbol  names,  it  is  inappropriate  to  make  lint  8-bit  clean. 
See  cc(lV)  for  an  explanation  about  why  cc  is  not  8-bit  clean. 

BUGS 

There  are  some  things  you  just  cannot  get  lint  to  shut  up  about. 

The  routines  exit(2V),  longjmp  (see  setjmp(3V))  and  other  functions  that  do  not  return  are  not  under¬ 
stood;  this  causes  various  incorrect  diagnostics. 

Libraries  created  by  the  -C  or  -o  options  will,  when  used  in  later  lint  runs,  cause  certain  errors  that  were 
reported  when  the  libraries  were  created  to  be  reported  again,  and  cause  line  numbers  and  file  names  from 
the  original  source  used  to  create  those  libraries  to  be  reported  in  error  messages.  For  these  reasons,  it  is 
still  useful  to  produce  stripped  down  lint  library  source  files  and  to  use  them  to  generate  lint  libraries. 
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In  -  make  hard  or  symbolic  links  to  files 
SYNOPSIS 

In  [  -fs  ]  filename  [  linkname  ] 

In  [  -fs  ]  pathname. . .  directory 

SYSTEM  V  SYNOPSIS 

/usr/5bin/ln  [  -fFs  ]  filename  [  linkname  ] 

In  [  -fFs  ]  pathname. . .  directory 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

In  creates  an  additional  directory  entry,  called  a  linky  to  a  file  or  directory.  Any  number  of  links  can  be 
assigned  to  a  file.  The  number  of  links  does  not  affect  other  file  attributes  such  as  size,  protections,  data, 
etc. 

filename  is  the  name  of  the  original  file  or  directory,  linkname  is  the  new  name  to  associate  with  the  file  or 
filename.  If  linkname  is  omitted,  the  last  component  of  filename  is  used  as  the  name  of  the  link. 

If  the  last  argument  is  the  name  of  a  directory,  symbolic  links  are  made  in  that  directory  for  each  pathname 
argument;  In  uses  the  last  component  of  each  pathname  as  the  name  of  each  link  in  the  named  directory. 

A  hard  link  (the  default)  is  a  standard  directory  entry  just  like  the  one  made  when  the  file  was  created. 
Hard  links  can  only  be  made  to  existing  files.  Hard  links  cannot  be  made  across  file  systems  (disk  parti¬ 
tions,  mounted  file  systems).  To  remove  a  file,  all  hard  links  to  it  must  be  removed,  including  the  name  by 
which  it  was  first  created;  removing  the  last  hard  link  releases  the  inode  associated  with  the  file. 

A  symbolic  link,  made  with  the  -s  option,  is  a  special  directory  entry  that  points  to  another  named  file. 
Symbolic  links  can  span  file  systems  and  point  to  directories.  In  fact,  you  can  create  a  symbolic  link  that 
points  to  a  file  that  is  currently  absent  from  the  file  system;  removing  the  file  that  it  points  to  does  not  affect 
or  alter  the  symbolic  link  itself. 

A  symbolic  link  to  a  directory  behaves  differently  than  you  might  expect  in  certain  cases.  While  an  Is(lV) 
on  such  a  link  displays  the  files  in  the  pointed-to  directory,  an  ‘Is  -I’  displays  information  about  the  link 
itself: 

example  %  In  -s  dir  link 
example  %  Is  link 
filel  file2  file3  file4 
example  %  Is  -1  link 

Irwxrwxrwx  1  user  7  Jan  11 23:27  link  ->  dir 

When  you  cd(l)  to  a  directory  through  a  symbolic  link,  you  wind  up  in  the  pointed-to  location  within  the 
file  system.  This  means  that  the  parent  of  the  new  working  directory  is  not  the  parent  of  the  symbolic  link, 
but  rather,  the  parent  of  the  pointed-to  directory.  For  instance,  in  the  following  case  the  final  working 
directory  is  /usr  and  not  /home/user/linktest. 
example  %  pwd 
/home/user/linktest 
exam  pie  %  In  -s  /usr/tmp  symiink 
example%  cd  symiink 
example%  cd .. 
example  %  pwd 
/usr 

C  shell  user’s  can  avoid  any  resulting  navigation  problems  by  using  the  pushd  and  popd  built-in  com¬ 
mands  instead  of  cd. 
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SYSTEM  V  DESCRIPTION 

The  System  V  version  of  In  behaves  as  described  above  except  for  the  following.  If  the  linkname  is  an 
existing  file  and  its  mode  does  not  forbid  writing,  then  its  contents  are  destroyed.  If  however  its  mode  does 
not  allow  writing,  the  mode  is  printed,  and  the  user  asked  for  a  response. 

OPTIONS 

— f  Force  a  hard  link  to  a  directory  —  this  option  is  only  available  to  the  super-user. 

-s  .  Create  a  symbolic  link  or  links. 

SYSTEM  V  OPTIONS 

-f  Force  files  to  be  linked  without  displaying  permissions,  asking  questions  or  reporting  errors. 

-F  Force  a  hard  link  to  a  directory  —  this  option  is  only  available  to  the  super-user. 

-s  Create  a  symbolic  link  or  links. 

EXAMPLE 

The  commands  below  illustrate  the  effects  of  the  different  forms  of  the  In  command: 

example  %  In  file  link 
example  %  Is  -F  file  link 
file  link 

example  %  In  -s  file  symlink 
example  %  Is  -F  file  symlink 
file  symlink@ 

example  %  Is  -li  file  link  symlink 
10606 -rw-r-r-  2  user  0  Jan  12  00:06  file 

10606  -rw-r-r-  2  user  0  Jan  12  00:06  link 

10607  Irwxrwxrwx  1  user  4  Jan  12  00:06  symlink  ->  file 
example  %  In  — s  nonesuch  devoid 

example  %  Is  -F  devoid 
devoid@ 

example  %  cat  devoid 
devoid:  No  such  file  or  directory 
example  %  In  -s  /proto/bin/*  /tmp/bin 
example  %  Is  -F  /proto/bin  /tmp/bin 
/proto^in: 

X*  y*  z* 

/tmp/bin: 

x@  y@  z@ 

SEE  ALSO 

cp(l),  Is(lV),  mv(l),  rm(l),  link(2V),  readlink(2),  stat(2V),  symlink(2) 

BUGS 

When  the  last  argument  is  a  directory,  simple  basenames  should  not  be  used  for  pathname  arguments.  If  a 
basename  is  used,  the  resulting  symbolic  link  points  to  itself: 

example  %  In  -s  file  /tmp 
example  %  Is  -1  /tmp/file 

Irwxrwxrwx  1  user  4  Jan  12  00:16  /tmp/file  ->  file 

example  %  cat  /tmp/file 

/tmp/file:  Too  many  levels  of  symbolic  links 
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^  To  avoid  this  problem,  use  full  pathnames,  or  prepend  a  reference  to  the  PWD  variable  to  files  in  the  work- 

_ j  ing  directory: 

example  %  rm  /tmp/file 
example  %  In  -s  $PWD/fae  /tmp 

Irwxrwxrwx  1  user  4  Jan  12  00:  Id  /tmp/file  ->  /home/user/subdir/file 
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NAME 

load,  bade  -  load  Application  SunOS  or  Developer’s  Toolkit  clusters 

SYNOPSIS 

load  [filename  . . .] 

loadc  [  cluster  . . .  ] 
loadc  app] 
loadc  devel 
AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

load  loads  the  optional  clusters  in  the  Application  SunOS  or  the  Developer’s  Toolkit  that  contain  the  files 
specified  in  the  filename  arguments,  loadc  loads  the  optional  clusters  in  the  Application  SunOS  or  the 
Developers  Toolkit  specified  in  the  cluster  arguments.  Specify  the  special  cluster  name  appl  with  loadc  to 
load  all  the  Application  SunOS  clusters.  Likewise,  specify  devel  to  loadc  to  load  all  the  Developer’s 
Toolkit  clusters. 

load  and  loadc  require  the  user  to  specify  the  distribution  medium,  either  3.5-inch  diskette  or  quarter-inch 
tape,  and  insert  the  diskette  or  tape.  The  user  will  be  asked  to  confirm  that  the  specified  medium  has  been 
inserted.  If  the  user  confirmation  is  negative,  no  software  will  be  loaded. 

Without  arguments,  load  and  loadc  display  a  summary  of  the  clusters  in  the  Application  SunOS  and 
Developer’s  Toolkit,  including  the  load  state  and  size  of  each  cluster. 

EXAMPLES 

To  load  the  cluster  that  contains  the  spell(l)  command: 
example  %  load  spell 

Enter  your  distribution  media  type  (1=1/4"  tape,  2=3.5"  diskette):  2 
Insert  diskette  n  to  load  the  spellcheck  cluster,  confirm  (y/n):  y 
Loading  the  spellcheck  cluster  ... 

The  spellcheck  cluster  has  been  loaded, 
space  used  by  clusters:  6021K  bytes 
total  space  remaining:  20432K  bytes 
example  % 

To  load  the  spellcheck  cluster: 

exam  pie  %  loadc  spellcheck 

Enter  your  distribution  media  type  (1=1/4"  tape,  2=3.5"  diskette):  2 
Insert  diskette  n  to  load  the  spellcheck,  confirm  (y/n):  y 
Loading  the  spellcheck  cluster  . . . 

The  spellcheck  cluster  has  been  loaded, 
space  used  by  clusters:  6021K  bytes 
total  space  remaining:  20432K  bytes 
example  % 

To  display  a  summary  of  the  clusters  in  the  Application  SunOS  and  Developer’s  Toolkit: 
example  %  load 

Application  SunOS  Optional  Clusters: 
available  cluster  size  (bytes) 


yes  accounting  265K 

no  advanced  admin  50 IK 
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Developer’s  Toolkit  Optional  Clusters: 
available  cluster  size  (bytes) 


no  basedevel  6907K 


space  used  by  clusters:  602 IK  bytes 
total  space  remaining:  20432K  bytes 
example% 

A  cluster  is  available  if  it  has  been  “loaded”  using  load  or  loadc  or  if  it  has  been  “mounted”  across  the  net¬ 
work. 

ENVIRONMENT 

LOADMEDIA  Used  to  specify  the  distribution  media  type  for  the  system.  It  can  be  set  to  diskette  to 
specify  3.5-inch  diskette  or  tape  to  specify  1/4"  tape.  If  it  is  set,  load  and  loadc  will  not 
ask  the  user  to  enter  the  distribution  media  type. 

FILES 

/usr/cluster/appl  where  Application  SunOS  clusters  are  loaded  (or  mounted) 

/usr/cluster/devel  where  Developer’s  Toolkit  clusters  are  loaded  (or  mounted) 

/usr/lib/load/+  data  files 

SEE  ALSO 

cluster(l),  unload(l),  toc(5) 

Sun386i  System  Setup  and  Maintenance 

DIAGNOSTICS 

Vl^rong  diskette!  tape 

An  incorrect  diskette  or  tape  was  inserted.  The  user  will  again  be  asked  to  insert  the  specified 
media. 

The  GAe  filename  is  not  in  any  of  the  optional  software  clusters. 

The  specified  file  is  not  part  of  the  Application  SunOS  or  Developer’s  Toolkit. 

There  is  no  cluster  cluster. 

The  specified  cluster  is  not  part  of  the  Application  SunOS  or  Developers  Toolkit. 

The  cluster  cluster  is  already  loaded,  overwrite?  (y/n): 

The  specified  cluster  appears  to  have  been  loaded  already.  Type  y  followed  by  RETURN  to  have 
the  cluster  loaded  or  n  followed  by  RETURN  to  cancel  the  loading  of  the  cluster. 

Cluster  cluster  requires  nK;  there  is  not  enough  disk  space. 

There  is  not  enough  disk  space  to  hold  the  specified  cluster. 

The  cluster  cluster  has  not  been  loaded. 

The  loading  of  the  specified  cluster  has  been  canceled  or  interrupted  by  the  user. 

The  Application  SunOS  (and/or)  Developers  Toolkit  are  mounted. 

The  Application  SunOS  or  Developers  Toolkit  or  both  are  mounted  across  the  network  and  can 
not  be  loaded  or  unloaded. 

The  tapeldiskette  drive  is  currently  in  use. 

You  are  trying  to  load  a  cluster  from  tape  (or  diskette)  and  another  process  currently  has  control  of 
the  tape  (or  diskette)  drive. 
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NAME 

loadkeys,  dumpkeys  -  load  and  dump  keyboard  translation  tables 
SYNOPSIS 

loadkeys  [  -e  ]  [filename  ] 

dumpkeys 

DESCRIPTION 

loadkeys 

loadkeys  reads  the  file  specified  by  filename  ^  and  modifies  the  keyboard  streams  module’s  translation 
tables.  If  no  file  is  specified,  and  the  keyboard  is  a  Type4  keyboard,  a  default  file  for  the  layout  indicated 
by  the  DIP  switches  on  the  keyboard.  The  file  is  in  the  format  specified  by  keytables(5). 

If  the  layout  code  in  the  DIP  switches  on  the  keyboard  has  the  hexadecimal  value  Qixdd,  the  file  loaded  by 
loadkeys  by  default  is  /usr/share/lib/keytables/layout  These  files  specify  only  the  entries  that  change 
between  the  different  Type-4  keyboard  layouts. 

dumpkeys 

dumpkeys  writes,  to  the  standard  output,  the  current  contents  of  the  keyboard  streams  module’s  translation 
tables,  in  the  format  specified  by  key  tables(5). 

OPTIONS 

-e  loadkeys  loads  the  requested  keytable  layout  information  into  the  EEPROM  keylables.  This  allows 
the  console  monitor  to  select  the  correct  key-values  when  a  non-US  keyboard  is  connected  to  the 
workstation. 


FILES 

/usr/share/lib/keytables/layout_^di 

default  keytable  files 

SEE  ALSO 

kb(4M),  keytables(5) 

BUGS 

The  -e  option  requires  EEPROM  rev  2.6  or  later. 
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NAME 

lockscreen,  lockscreen_default  —  maintain  Sun  View  context  and  prevent  unauthorized  access 
SYNOPSIS 

lockscreen  [  —enr  ]  [  — b  program  ]  [  — t  seconds  ]  [  gfx-program  [  gfx-program-arguments  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  Users  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  about  installing  optional  software, 

DESCRIPTION 

lockscreen  is  a  SunView  utility  that  locks  the  screen  against  unauthorized  access  while  preserving  the  state 
of  the  SunView  display.  It  clears  the  workstation  screen  to  black,  and  then  runs  gfx-program,  which  typi¬ 
cally  provides  a  moving  graphics  display  to  reduce  phosphor  bum.  When  no  gfx-program  is  provided,  a 
suitable  default  program  is  run. 

lockscreen  requires  the  user’s  password  before  restoring  the  window  context.  When  any  keyboard  or 
mouse  button  is  pressed,  the  graphics  screen  is  replaced  by  a  password  screen  that  displays  the  user  name, 
a  small  box  with  a  bouncing  logo,  and  a  prompt  for  the  user’s  password.  If  the  user  has  no  password,  or  if 
the  — n  option  is  used,  the  window  context  is  simply  restored. 

When  the  password  screen  appears: 

•  Restore  the  window  context  by  entering  the  user’s  password  followed  by  a  RETURN  (this 
password  is  not  echoed  on  the  screen)  or, 

•  Point  to  the  black  box  and  click  the  left  button  to  return  to  the  graphics  display. 

If  neither  of  the  above  actions  is  taken,  gfx _program  will  resume  execution  after  the  interval  specified  with 
the  -t  option. 

OPTIONS 

-e  Add  the  Exit  Desktop  choice  to  the  password  screen.  If  pointed  to  and  clicked,  the  SunView 
environment  is  exited  and  the  current  user  is  logged  out. 

-n  Require  no  password  to  reenter  the  window  environment. 

-r  Allow  the  use  of  the  user  name  root  in  the  ‘Name:’  field  of  the  password  screen.  Normally,  root 

is  not  accepted  as  a  valid  user  name. 

-b  program 

Allow  an  additional  program  to  be  mn  as  a  child  process  of  lockscreen.  This  background  process 
could  be  a  compile  server  or  some  other  useful  program  that  the  user  wants  run  while  lockscreen 
is  running.  No  arguments  are  passed  to  this  program. 

~i  seconds 

After  seconds  seconds,  clear  the  password  screen  and  restart  gfx-program.  The  default  is  5 
minutes  (300  seconds). 

[  gfx-program  ]  [  gfx-program-arguments  ] 

Run  this  program  after  clearing  the  screen  to  black.  When  no  program  argument  is  present,  lock- 
screen  tries  to  run  lockscreen_default  if  it  is  in  the  standard  search  path;  otherwise,  a  bouncing 
Sun  logo  appears.  When  gfx-program-arguments  are  specified  and  the  gfx-program  is  not,  the 
arguments  are  passed  to  lockscreen_default.  lockscreen_default  is  typically  a  non-interactive 
graphics  program  (see  graphics_demos(6)).  lockscreen  does  not  search  for  lockscreen_default 
when  the  gfx-program  is  specified  explicitly  as  an  empty  argument  (an  adjacent  pair  of  quote- 
marks). 

FILES 

/usr/bin/lockscreen_default 

Default  gfx-program.  This  displays  a  series  of  life(6)  patterns.  If  a  file  named 
lockscreen_default  appears  earlier  in  the  search  path,  that  file  is  used  instead. 
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SEE  ALSO 

login(l),  sunview(l) 

BUGS 

lockscreen  is  more  secure  when  gfx-program  are  not  specified  and  when  lockscreen  default  is  not  in  the 
search  path.  To  improve  security,  enter  the  following  command  as  root,  or  start  lockscreen  with  an  empty 
argument  (see  OPTIONS,  above). 

#  mv  /usr/bin/lockscreen_default  /usr/bin/lockscreen_default- 
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NAME 

logger  -  add  entries  to  the  system  log 
SYNOPSIS 

logger  [  — t  tag  ]  [  — p  priority  ]  [  ~i  ]  [  — f filename  ]  [  message  ] . . . 

DESCRIPTION 

logger  provides  a  method  for  adding  one-line  entries  to  the  system  log  file  from  the  command  line.  One  or 
more  message  arguments  can  be  given  on  the  command  line,  in  which  case  each  is  logged  immediately. 
Otherwise,  ^filename  can  be  specified,  in  which  case  each  line  in  the  file  is  logged.  If  neither  is  specified! 
logger  reads  and  logs  messages  on  a  line-by-line  basis  from  the  standard  input. 

OPTIONS 


-t  tag  Mark  each  line  added  to  the  log  with  the  specified  tag. 

-p  priority  Enter  the  message  with  the  specified  priority.  The  message  priority  can  be  specified  numer¬ 
ically,  or  as  ^facility. level  pair.  For  example,  ‘-p  locaB.info'  assigns  the  message  priority 
to  the  info  level  in  the  local3  facility.  The  default  priority  is  user  .notice. 

Log  the  process  ID  of  the  logger  process  with  each  line. 

-(filename  Use  the  contents  of  filename  as  the  message  to  log. 

message  If  this  is  unspecified,  either  the  file  indicated  with  — f  or  the  standard  input  is  added  to  the 
log. 


EXAMPLES 

logger  System  rebooted 


will  log  the  message  ‘System  rebooted’  to  the  facility  at  priority  notice  to  be  treated  by  syslogd  as  other 
messages  to  the  facility  notice  are. 

logger  -p  local0.notice  -t  HOSTIDM  -f /dev/idmc 

will  read  from  the  file  /dev/idmc  and  will  log  each  line  in  that  file  as  a  message  with  the  tag  ‘HOSTIDM’  at 
priority  notice  to  be  treated  by  syslogd  as  other  messages  to  the  facility  localO  are. 

SEE  ALSO 

syslog(3),  syslogd(8) 
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NAME 

login  -  log  in  to  the  system 
SYNOPSIS 

login  [  -p  ]  [  username  ] 

DESCRIPTION 

login  signs  username  on  to  the  system  initially;  login  may  also  be  used  at  any  time  to  change  from  one  user 
ID  to  another. 

When  used  with  no  argument,  login  requests  a  user  name  and  password  (if  appropriate).  Echoing  is  turned 
off  (if  possible)  while  typing  the  password.  Note:  the  number  of  significant  characters  in  a  password  is  8. 
See  passwd(l). 

If  password  aging  is  enabled  and  the  password  corresponding  to  the  user  name  has  expired,  the  user  will  be 
prompted  for  a  new  password.  The  user  has  to  successfully  modify  his  password  for  login  to  proceed.  See 
passwd(l). 

When  successful,  login  updates  accounting  files,  prints  disk  usage  and  limits  (by  running  quota(l),)  prints 
the  message  of  the  day,  informs  you  of  the  existence  of  any  mail,  and  displays  the  time  you  last  logged  in. 
None  of  these  messages  is  printed  if  there  is  a  .hushlogin  file  in  your  home  directory.  This  is  mostly  used 
to  make  life  easier  for  nonhuman  users,  such  as  uucp(lC). 

login  initializes  the  user  and  group  IDs  and  the  working  directory,  then  starts  a  command  interpreter  shell 
(usually  either  sh(l)  or  csh(l))  according  to  specifications  found  in  the  file  /etc/passwd.  Argument  0  of  the 
command  interpreter  is  the  name  of  the  command  interpreter  with  a  leading  dash  (‘-’)  prepended. 

login  also  modifies  the  environment  (environ(5V))  with  information  specifying  home  directory,  command 
interpreter,  terminal-type  (if  available)  and  username.  The  -p  argument  preserves  the  remainder  of  the 
environment,  otherwise  any  previous  environment  is  discarded. 

The  super-user  root  may  only  log  in  on  those  terminals  marked  as  “secure”  in  the  /etc/ttytab  file.  Other¬ 
wise,  the  super-user  must  log  in  as  an  ordinary  user  and  become  super-user  using  su(lv).  For  example,  if 
the  file  contained: 

console  "/etc/getty  Console-9600"  sun  on  secure 

ttyOO  "/etc/getty  Console-9600"  sun  on 


the  super-user  could  only  log  in  directly  on  the  console.  See  ttytab(5)  for  a  discussion  of  “secure”  and 
other  getty(8)  options  used  in  /etc/ttytab. 

If  the  file  /etc/nologin  exists,  login  prints  its  contents  on  the  user’s  terminal  and  exits.  This  is  used  by  shut- 
down(8)  to  stop  logins  when  the  system  is  about  to  go  down. 

The  login  command,  recognized  by  sh(l)  and  csh(l),  is  executed  directly  (without  forking),  and  terminates 
that  shell.  To  resume  working,  you  must  log  in  again. 

login  times  out  and  exits  if  its  prompt  for  input  is  not  answered  within  a  reasonable  time. 

When  the  Bourne  shell  (sh)  starts  up,  it  reads  a  file  called  .profile  from  your  home  directory  (that  of  the 
username  you  use  to  log  in).  When  the  C  shell  (csh)  starts  up,  it  reads  a  file  called  .cshrc  firom  your  home 
directory,  and  then  reads  a  file  called  .login. 

The  shells  read  these  files  only  if  they  are  owned  by  the  person  logging  in. 

OPTIONS 

-p  Preserve  any  existing  environment  variables  and  their  values;  otherwise  the  previous  environment 
is  discarded. 

FILES 

/etc/utmp  accounting 

/var/adm/wtmp  accounting 

/var/adm/lastlog  time  of  last  login 
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/etc/ttytab 

/usr/ucb/quota 

/var/spool/mail/* 

/etc/motd 

/etc/passwd 

/etc/nologin 

7.hushlogin 

.login 

.profile 


terminal  types 
quota  check 
mail 

message-of-the-day 
password  file 
stop  login,  print  message 
makes  login  quieter 


SEE  ALSO 

csh(l),  mail(l),  passwd(l),  quota(I),  rlogin(lC),  sh(I),  uucp(lC),  environ(5V),  fbtab(5),  passwd(5), 
svdtab(5),  utmp(5V).  getty(8),  init(8),  sbutdowii(8) 

DIAGNOSTICS 

Login  incorrect  If  the  name  or  the  password  is  bad  (or  mistyped). 

No  Shell 


cannot  open  password  file 

no  directory  Ask  your  system  administrator  for  assistance. 

NOTES 

The  following  options  are  undocumented,  and  not  intended  for  the  user.  The  -r  option  is  used  by  the 
remote  login  server,  rtogind(8C)  to  force  login  to  enter  into  an  initial  connection  protocol,  -h  is  used  by 
telnetd(8C)  and  other  servers  to  list  the  host  from  which  the  connection  was  receiv^. 

The  following  warnings  apply  when  login  account  names  contain  characters  outside  the  range  of  7-bit 
ASCn: 

•  A  user  cannot  rlogin  to  account-name  containing  8-bit  characters  from  a  system  that  does  not  handle 
8-bit  characters. 

•  A  user  cannot  log  in  to  account-name  containing  8-bit  characters  from  a  7-bit  ASCH  terminal  (through  a 
modem,  for  example). 

•  Several  parts  of  the  C  library  are  not  tested  for  8-bit  user  names. 

•  Codeset  mapping  can  vary  between  systems,  so  an  8-bit  pattern  can  represent  different  characters  on 
different  sytems. 

•  Password  algorithms  do  not  work  with  8-bit  characters  in  the  password. 
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NAME 

logname  -  get  the  name  by  which  you  logged  in 

SYNOPSIS 

logname 

DESCRIPTION 

logname  returns  the  contents  of  the  environment  variable  LOGNAME,  which  is  set  when  a  user  logs  into 
the  system. 

FILES 

/etc/profile 
SEE  ALSO 

env(l),  login(l),  environ(5V) 

NOTES 

The  following  warnings  apply  when  login  accounts  contain  characters  outside  the  range  of  7-bil  ASCII; 

•  A  user  cannot  rlogin  to  account-name  containing  8-bit  characters  from  a  system  that  does  not  handle 
8-bit  characters. 

•  A  user  cannot  log  in  to  account-name  containing  8-bil  characters  from  a  7-bit  ASCII  terminal  (through  a 
modem,  for  example). 

•  Several  parts  of  the  C  library  are  not  tested  for  8-bit  user  names. 

•  Codeset  mapping  can  vary  between  systems,  so  an  8-bit  pattern  can  represent  different  characters  on 
different  sytems. 

•  Password  algorithms  do  not  work  with  8-bit  characters. 
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NAME 

look  —  find  words  in  the  system  dictionary  or  lines  in  a  sorted  list 
SYNOPSIS 

look  [  -df  ]  [  -tc  ]  string  [filename  ] 

DESCRIPTION 

look  consults  a  sorted  filename  and  prints  all  lines  that  begin  with  string. 

If  no  filename  is  specified,  look  uses  /usr/dict/words  with  collating  sequence  — df. 

OPTIONS 

-d  Dictionary  order.  Only  letters,  digits,  TAB  and  SPACE  characters  are  used  in  comparisons, 

-f  Fold  case.  Upper  case  letters  arenT  disunguished  from  lower  case  in  comparisons. 

— tc  Set  termination  character.  All  characters  to  the  right  of  c  in  string  are  ignored. 

FILES 

/usr/dict/words 
SEE  ALSO 

grep(lV),  sort(lV) 
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NAME 

lookbib  -  find  references  in  a  bibliographic  database 

SYNOPSIS 

lookbib  database 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

A  bibliographic  reference  is  a  set  of  lines,  constituting  fields  of  bibliographic  information.  Each  field  starts 
on  a  line  beginning  with  a  *%*,  followed  by  a  key-letter,  then  a  blank,  and  finally  the  contents  of  the  field, 
which  may  continue  until  the  next  line  starting  with  ‘ 

lookbib  uses  an  inverted  index  made  by  indxbib  to  find  sets  of  bibliographic  references.  It  reads  keywords 
typed  after  the  *>’  prompt  on  the  terminal,  and  retrieves  records  containing  all  these  keywords.  If  nothing 
matches,  nothing  is  returned  except  another  prompt. 

It  is  possible  to  search  multiple  databases,  as  long  as  they  have  a  common  index  made  by  indxbib(l).  In 
that  case,  only  the  first  argument  given  to  indxbib  is  specified  to  lookbib. 

If  lookbib  does  not  find  the  index  files  (the  .i[abc]  files),  it  looks  for  a  reference  file  with  the  same  name  as 
the  argument,  without  the  suffixes.  It  creates  a  file  with  a  jg  suffix,  suitable  for  use  with  fgrep  (see 
grep(lV)).  lookbib  then  uses  this  fgrep  file  to  find  references.  This  method  is  simpler  to  use,  but  the  .ig 
file  is  slower  to  use  than  the  a[abc]  files,  and  does  not  allow  the  use  of  multiple  reference  files. 

FILES 

x.ia 
x.ib 
jc.ic 
x\% 

SEE  ALSO 

addbib(l),  grep(lV),  indxbib(l),  refer(l),  roffbib(l),  sortbib(l) 

Formatting  Documents 

BUGS 

Probably  all  dates  should  be  indexed,  since  many  disciplines  refer  to  literature  written  in  the  1800s  or  ear¬ 
lier. 


index  files 
reference  file 
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NAME 

[order  -  find  an  ordering  relation  for  an  object  library 
SYNOPSIS 

lorder  filename. . . 

DESCRIPTION 

Give  lorder  one  or  more  object  or  library  archive  (see  ar(lV))  filenames,  and  it  lists  pairs  of  object  file 
names  —  meaning  that  the  first  file  of  the  pair  refers  to  external  identifier  defined  in  the  second  —  to  the 
standard  output.  lorder’s  output  may  be  processed  by  tsort(l)  to  find  an  ordering  of  a  library  suitable  for 
one-pass  access  by  ld(l). 

EXAMPLE 

This  brash  one-liner  intends  to  build  a  new  library  from  existing  .0  files, 
ar  cr  library '  lorder  *.o  |  tsorf 

The  ranUb(l),  command  converts  an  ordered  archive  into  a  randomly  accessed  library  and  makes  lorder 
unnecessary. 

SEE  ALSO 

ar(lV),  ld(l),  ranlib(l),  tsort(l) 

BUGS 

The  names  of  object  files,  in  and  out  of  libraries,  must  end  with  ‘.o';  otherwise,  nonsense  results. 
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NAME 

Ip,  cancel  -  send/cancel  requests  to  a  printer 
SYNOPSIS 

Ip  [  -cmsw  ]  [  -ddest  ]  [  -nnumber  ]  [  -ooption  ]  [  -ititle  ]  filename . . . 
cancel  [  ids  ]  [  printers  ] 

DESCRIPTION 

Ip  arranges  for  the  named  files  and  associated  information  (collectively  called  a  request)  to  be  printed  by  a 
line  printer.  If  no  file  names  are  mentioned,  the  standard  input  is  assumed.  The  file  name  stands  for  the 
standard  input  and  may  be  supplied  on  the  command  line  in  conjunction  with  named  filenames.  The  order 
in  which  filenames  appear  is  the  same  order  in  which  they  will  be  printed. 

Ip  associates  a  unique  id  with  each  request  and  prints  it  on  the  standard  output.  This  id  can  be  used  later  to 
cancel  (see  cancel)  or  find  the  status  (see  lpstat(l))  of  the  request. 

cancel  cancels  line  printer  requests.  The  command  line  arguments  may  be  either  request  ids  (as  returned 
by  lp(l))  or  printer  names.  When  ids  are  specified,  cancel  removes  the  jobs  corresponding  to  the  ids  on 
the  destination  printer.  See  the  -d  option  for  details  on  how  the  default  destination  printer  is  obtained.  For 
a  complete  list  of  printers,  use  Ipstat(l).  Specifying  a  request  id  cancels  the  associated  request  even  if  it  is 
currently  printing.  Specifying  a  printer  cancels  the  request  which  is  currently  printing  on  that  printer.  In 
either  case,  the  cancellation  of  a  request  that  is  currently  printing  frees  the  printer  to  print  its  next  available 
request. 

OPTIONS 

The  following  options  to  Ip  may  appear  in  any  order  and  may  be  intermixed  with  file  names: 

-c  Make  copies  of  the  filenames  to  be  printed  immediately  when  Ip  is  invoked.  Otherwise, 

filenames  will  not  be  copied,  but  will  be  linked  whenever  possible.  If  the  -c  option  is  not 
given,  then  the  user  should  be  careful  not  to  remove  any  of  the  filenames  before  the  request  has 
been  printed  in  its  entirety.  It  should  also  be  noted  that  in  the  absence  of  the  -c  option,  any 
changes  made  to  the  named  filenames  after  the  request  is  made  but  before  it  is  printed  will  be 
reflected  in  the  printed  output. 

-m  Send  mail  (see  mail(l))  after  the  files  have  been  printed.  By  default,  no  mail  is  sent  upon  nor¬ 

mal  completion  of  the  print  request. 

-s  Suppress  messages  from  /p(l)  such  as  ‘request  id  is  . . 

-w  Write  a  message  on  the  user’s  terminal  after  ihQ  filenames  have  been  printed.  If  the  user  is  not 

logged  in  locally,  then  mail  will  be  sent  instead. 

-ddest  Choose  dest  as  the  printer  that  is  to  do  the  printing.  By  default,  dest  is  taken  from  the  environ¬ 
ment  variable  LPDEST  (if  it  is  set).  Otherwise,  dest  will  be  taken  from  the  environment  vari¬ 
able  PRINTER.  If  PRINTER  is  not  defined  either,  then  the  default  destination  for  the  computer 
system  is  used.  Destination  names  vary  between  systems  (see  Ipstat(l)). 

-nnumber  Print  number  copies  (default  of  1)  of  the  output. 

-ooption  Specify  printer-dependent  options.  Several  such  options  may  be  collected  by  specifying  the 
-o  option  more  than  once. 

-ititle  Print  title  on  the  banner  page  of  the  output 

FILES 

/etc/term  cap 
SEE  ALSO 

Ipstat(l),  Ipr(l),  Iprm(l),  mail(l),  lpc(8),  lpd(8) 
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NAME 

Ipq  ~  display  the  queue  of  printer  jobs 
SYNOPSIS 

Ipq  [  -Vprinter  ][-!][+[  interval  ]  ]  [joM . . .  ]  [  username  . . .  ] 

DESCRIPTION 

Ipq  displays  the  contents  of  a  printer  queue.  It  reports  the  status  of  Jobs  specified  by  job#,  or  all  jobs 
owned  by  the  user  specified  by  username .  Ipq  reports  on  all  jobs  in  the  default  printer  queue  when  invoked 
with  no  arguments. 

For  each  print  job  in  the  queue,  Ipq  reports  the  user’s  name,  current  position,  the  names  of  input  files 
comprising  the  job,  the  job  number  (by  which  it  is  referred  to  when  using  Iprin(l))  and  the  total  size  in 
bytes.  Normally,  only  as  much  information  as  will  fit  on  one  line  is  displayed.  Jobs  are  normally  queued 
on  a  first-in-first-out  basis.  Filenames  comprising  a  job  may  be  unavailable,  such  as  when  Ipr  is  used  at  the 
end  of  a  pipeline;  in  such  cases  the  filename  field  indicates  “(standard  input)”. 

If  Ipq  warns  that  there  is  no  daemon  present  (that  is,  due  to  some  malfunction),  the  lpc(8)  command  can  be 
used  to  restart  a  printer  daemon. 


OPTIONS 

-P  printer  Display  information  about  the  queue  for  the  specified  printer.  In  the  absence  of  the  ~P 

option,  the  queue  to  the  printer  specified  by  the  PRINTER  variable  in  the  environment  is 
used.  If  the  PRINTER  variable  isn’t  set,  the  queue  for  the  default  printer  is  used. 


-I  Display  queue  information  in  long  format;  includes  the  name  of  the  host  from  which  the 

job  originated. 

-t-[  interval  ] 

Display  the  spool  queue  periodically  until  it  empties.  This  option  clears  the  terminal 
screen  before  reporting  on  the  queue.  If  an  interval  is  supplied,  Ipq  sleeps  that  number 
of  seconds  in  between  reports. 


FILES 

/etc/termcap 

/etc/printcap 

/var^pool/l* 

/var/spool/l*/cf* 

/var/spool/l*/lock 


for  manipulating  the  screen  for  repeated  display 

to  determine  printer  characteristics 

spooling  directory,  as  determined  from  printcap 

control  files  specifying  jobs 

lock  file  to  obtain  the  currently  active  job 


SEE  ALSO 

Ipr(l),  Iprm(l),Ipc(8),lpd(8) 


DIAGNOSTICS 

printer  is  ready  and  printing 

The  Ipq  program  checks  to  see  if  there  is  a  printer  daemon.  If  the  daemon  is  hung,  the  super-user 
can  abort  the  current  daemon  and  start  a  new  one  using  Ipc(8). 

Waiting  for  printer  to  become  ready  (offline  ?) 

The  daemon  could  not  open  the  printer  device.  The  printer  may  be  turned  off-line.  This  message 
can  also  occur  if  a  printer  is  out  of  paper,  the  paper  is  jammed,  and  so  on.  Another  possible  cause 
is  that  a  process,  such  as  an  output  filter,  has  exclusive  use  of  the  device.  The  only  recourse  in  this 
case  is  to  kill  the  offending  process  and  restart  the  printer  with  Ipc. 

waiting  for  host  to  come  up 

A  daemon  is  trying  to  connect  to  the  remote  machine  named  host,  in  order  to  send  the  files  in  the 
local  queue.  If  the  remote  machine  is  up,  Ipd  on  the  remote  machine  is  probably  dead  or  hung  and 
should  be  restarted  using  Ipc. 
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sending  to  host 

The  files  are  being  transferred  to  the  remote  host,  or  else  the  local  daemon  has  hung  while  trying 
to  transfer  the  files. 

Warning:  printer  is  down 

The  printer  has  been  marked  as  being  unavailable  with  Ipc. 

Warning:  no  daemon  present 

The  Ipd  process  overseeing  the  spooling  queue,  as  indicated  in  the  “lock”  file  in  that  directory, 
does  not  exist.  This  normally  occurs  only  when  the  daemon  has  unexpectedly  died.  Check  the 
printer’s  error  log  for  a  diagnostic  from  the  deceased  process;  you  can  restart  the  printer  daemon 
with  Ipc. 

BUGS 

Ipq  may  report  unreliably.  The  status  as  reported  may  not  always  reflect  the  actual  state  of  the  printer. 
Under  some  circumstances,  Ipq  reports  that  a  printer  is  ready  and  printing  when  the  daemon  is,  in  fact, 
hung. 

Output  formatting  is  sensitive  to  the  line  length  of  the  terminal;  this  can  result  in  widely-spaced  columns. 
Ipq  is  sometimes  unable  to  open  various  files  when  the  lock  file  is  malformed. 
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NAME 

Ipr  ~  send  a  job  to  the  printer 


SYNOPSIS 

Ipr  [  -Fprinter  ]  [  -^copies  ]  [  -Cclass  ]  [  ~3job  ]  [  -T title  ]  [  -i  [  indent  ]  ]  [  -1234font  ] 

[  -wools  ]  [  -r  ]  [  -m  ]  [  -h  ]  [  ”S  ]  f  -filter-option  ]  [filename  . . .  ] 

DESCRIPTION 

Ipr  creates  a  printer  job  in  a  spooling  area  for  subsequent  printing  as  facilities  become  available.  Each 
printer  job  consists  of  a  control  file  and  one  or  more  data  files.  The  data  files  are  copies  of  (or,  with  -s  , 
symbolic  links  to)  each  filename  you  specify.  The  spool  area  is  managed  by  the  line  printer  daemon, 
lpd(8).  Jobs  that  specify  a  printer  on  a  remote  machine  are  forwarded  by  Ipd. 

Ipr  reads  firom  the  standard  input  if  no  files  are  specified. 


OPTIONS 

-Pprinter 

-^copies 


-Cclass 


-Jjob 
-Ttitle 
-i[  indent  ] 

-Ifont 
-2  font 
-3font 
-4font 


Send  output  to  the  named  printer.  Otherwise  send  output  to  the  printer  named  in  the 
PRINTER  environment  variable,  or  to  the  default  printer.  Ip. 

Produce  the  number  of  copies  indicated  for  each  named  file.  For  example: 

example  %  Ipr  -#3  indexx  lookup.c 

produces  three  copies  of  index.c,  followed  by  three  copies  of  lookups.  On  the  other 
hand, 

example  %  cat  index.c  lookup.c  |  Ipr  -#3 

generates  three  copies  of  the  concatenation  of  the  files. 

Print  class  as  the  job  classification  on  the  burst  page.  For  example, 

example  %  Ipr  -C  Operations  new,index.c 

replaces  the  system  name  (the  name  returned  by  hostname)  with  “Operations”  on  the 
burst  page,  and  prints  the  file  new. index.c. 

Print  Job  as  the  job  name  on  the  burst  page.  Normally,  Ipr  uses  the  first  file’s  name. 

Use  title  instead  of  the  file  name  for  the  title  used  by  pr(l  V). 

Indent  output  indent  SPACE  characters.  Eight  SPACE  characters  is  the  default.  The 
indent  is  passed  to  the  input  filter.  If  no  input  filter  is  present,  this  option  is  ignored. 


Mount  the  specified /ont  on  font  position  1,  2,  3  or  4,  The  daemon  will  construct  a  .rail- 
mag  file  in  the  spool  directory  that  indicates  the  mount  by  referencing 
/usr/lib/vfont/font. 


-wcols 


Use  cols  as  the  page  width  for  pr. 


-r 

-m 

-h 

-s 


Remove  the  file  upon  completion  of  spooling,  or  upon  completion  of  printing  with  the  -s 
option. 

Send  mail  upon  completion. 

Suppress  printing  the  burst  page. 

Create  a  symbolic  link  from  the  spool  area  to  the  data  files  rather  than  trying  to  copy 
them  (so  large  files  can  be  printed).  This  means  the  data  files  should  not  be  modified  or 
removed  until  they  have  been  printed.  This  option  can  be  used  to  avoid  truncating  files 
larger  than  the  maximum  given  in  the  mx  capability  of  the  printcap(5)  entry,  -s  only 
prevents  copies  of  local  files  from  being  made.  Jobs  from  remote  hosts  are  copied  any¬ 
way.  -s  only  works  with  named  data  files;  if  the  Ipr  command  is  at  the  end  of  a  pipe¬ 
line,  the  data  is  copied  to  the  spool. 
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filter-option  The  following  single  letter  options  notify  the  line  printer  spooler  that  the  files  are  not 
standard  text  files.  The  spooling  daemon  will  use  the  appropriate  filters  to  print  the  data 
accordingly. 

-p  Use  pr  to  format  the  files  (Ipr  -p  is  very  much  like  ‘pr  |  Ipr’). 

-1  Print  control  characters  and  suppress  page  breaks. 

— t  The  files  contain  troff(l)  (cat  phototypesetter)  binary  data. 

— n  The  files  contain  data  from  ditrofT  (device  independent  troff). 

-d  The  files  contain  data  from  tex  (DVT  format  from  Stanford). 

-g  The  files  contain  standard  plot  data  as  produced  by  the  pIot(3X)  routines  (see 

also  plot(lG)  for  the  filters  used  by  the  printer  spooler). 

-V  The  files  contain  a  raster  image,  see  rasterfile(5).  The  printer  must  support  an 
appropriate  imaging  model  such  as  PostScript  in  order  to  print  the  image. 

-c  The  files  contain  data  produced  by  cifplot. 

-f  Interpret  the  first  character  of  each  line  as  a  standard  FORTRAN  carriage  control 
character. 


If  no  filter-option  is  given  (and  the  printer  can  interpret  PostScript),  the  string  '%!’  as 
the  first  two  characters  of  a  file  indicates  that  it  contains  PostScript  commands. 

These  filter  options  offer  a  standard  user  interface,  and  all  options  may  not  be  available 
for,  nor  applicable  to,  all  printers. 


FILES 

/etc/passwd 

/etc/printcap 

/usr/lib/lpd 

/var/spooI/1* 

/var/spool/l*/cf+ 

/var/spooI/l*/df* 

/var/spooI/I*/tf+ 

/usr/lib/vfont/font 


personal  identification 
printer  capabilities  data  base 
line  printer  daemon 
directories  used  for  spooling 
daemon  control  files 
data  files  specified  in  ‘cf  files 
temporary  copies  of  ‘cf’  files 


SEE  ALSO 

Ipq(l),  Iprm(l),  plot(lG),  pr(lV),  screendump(l),  troff(l),  plot(3X),  printcap(5),  rasterfile(5),  lpc(8), 
lpd(8) 

DIAGNOSTICS 

Ipr:  copy  file  is  too  large 

A  file  is  determined  to  be  too  “large”  to  print  by  copying  into  the  spool  area.  Ipr  truncates  the  file, 
and  prints  as  much  of  it  as  it  can.  The  maximum  file  length  is  specified  by  the  mx  capability  of 
the  priiitcap(5)  entry  for  the  printer.  If  no  mx  capability  is  specified,  the  default  limit  is  1000 
Kbytes.  Use  the  -s  option  as  defined  above  to  make  a  symbolic  link  to  the  file  instead  of  copying 
it 


Ipr:  printer :  unknown  printer 

The  printer  was  not  found  in  the  printcap  database.  Usually  this  is  a  typing  mistake;  however,  it 
may  indicate  a  missing  or  incorrect  entry  in  the  /etc/printcap  file. 

Ipr:  printer :  jobs  queued,  but  cannot  start  daemon. 

The  connection  to  Ipd  on  the  local  machine  failed.  This  usually  means  the  printer  server  started  at 
boot  time  has  died  or  is  hung.  Check  the  local  socket  /dev/printer  to  be  sure  it  still  exists  (if  it 
does  not  exist,  there  is  no  Ipd  process  running). 
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Ipr:  printer :  printer  queue  is  disabled 

This  means  the  queue  was  turned  off  with 

exaniple%  /usr/etc/lpc  disable  printer 

to  prevent  Ipr  from  putting  files  in  the  queue.  This  is  normally  done  by  the  system  manager  when 
a  printer  is  going  to  be  down  for  a  long  time.  The  printer  can  be  turned  back  on  by  a  super-user 
with  Ipc. 

If  a  connection  to  Ipd  on  the  local  machine  cannot  be  made  Ipr  will  say  that  the  daemon  cannot  be 
started.  Diagnostics  may  be  printed  in  the  daemon  log  file  regarding  missing  spool  files  by  Ipd. 

BUGS 

Command-line  options  cannot  be  combined  into  a  single  argument  as  with  some  other  commands.  The 
command: 

Ipr  -fs 

is  not  equivalent  to 
Ipr  -f  -s 

Placing  the  -s  flag  first,  or  writing  each  option  as  a  separate  argument,  makes  a  link  as  expected. 

Ipr  -p  is  not  precisely  equivalent  to  pr  |  Ipr.  Ipr  — p  puts  the  current  date  at  the  top  of  each  page,  rather 
than  the  date  last  modified. 

Fonts  for  troff(l)  and  TgX®  reside  on  the  printer  host.  It  is  currently  not  possible  to  use  local  font 
libraries. 

Ipr  refuses  to  print  a.out  files  and  library  archives. 

The  -s  option  only  avoids  copying  the  data  file  to  the  spool  directory  of  the  local  machine.  If  the  printer 
for  a  job  resides  on  a  remote  machine,  the  data  file  will  be  copied  to  the  remote  spool  directory  in  all  cases. 
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NAME 

Iprm  “  remove  jobs  from  the  printer  queue 
SYNOPSIS 

Iprm  [  -Pprinter  ]  [  -  ]  [job  # . . .  ]  [  username  ...  ] 


DESCRIPTION 

Iprm  removes  a  job  or  jobs  from  a  printer’s  spooling  queue.  Since  the  spool  directory  is  protected  from 
users,  using  Iprm  is  normally  the  only  method  by  which  a  user  can  remove  a  job. 

Without  any  arguments,  Iprm  deletes  the  job  that  is  currently  active,  provided  that  the  user  who  invoked 
Iprm  owns  that  job. 

When  the  super-user  specifies  a  username,  Iprm  removes  all  jobs  belonging  to  that  user. 

You  can  remove  a  specific  job  by  supplying  its  job  number  as  an  argument,  which  you  can  obtain  using 
Ipq(l).  For  example: 


example  %  Ipq-Phost 
host  is  ready  and  printing 

Rank  Owner  Job  Files  Total  Size 

active  wendy  385  standard  input  35501  bytes 

example  %  Iprm -Phost  385 


Iprm  reports  the  names  of  any  files  it  removes,  and  is  silent  if  there  are  no  applicable  jobs  to  remove. 

Iprm  kills  the  active  printer  daemon,  if  necessary,  before  removing  spooled  jobs;  it  restarts  the  daemon 

when  through. 

OPTIONS 

-^printer  Specify  the  queue  associated  with  a  specific  printer.  Otherwise  the  value  of  the 

PRINTER  variable  in  the  environment  is  used.  If  this  variable  is  unset,  the  queue  for  the 
default  printer  is  used. 

-  Remove  all  jobs  owned  by  you.  If  invoked  by  the  super-user,  all  jobs  in  the  spool  are 

removed.  (Job  ownership  is  determined  by  the  user’s  login  name  and  host  name  on  the 
machine  where  the  Ipr  command  was  invoked). 


FILES 

/etc/printcap 

/var/spool/* 

/var/spool/l*/lock 


printer  characteristics  file 
spooling  directories 

lock  file  used  to  obtain  the  pid  of  the  current  daemon  and  the  job  number  of  the 
currently  active  job 


SEE  ALSO 

lpr(l),lpq(l),lpd(8) 


DIAGNOSTICS 

Iprm:  printer ;  cannot  restart  printer  daemon 

The  connection  to  Ipd  on  the  Icxial  machine  failed.  This  usually  means  the  printer  server  started  at 
boot  time  has  died  or  is  hung.  If  it  is  hung,  the  master  lpd(8)  daemon  may  have  to  be  killed  and  a 
new  one  started. 


BUGS 

Since  race  conditions  are  possible  when  updating  the  lock  file,  an  active  job  may  be  incorrectly  identified 
for  removal  by  an  Iprm  command  issued  with  no  arguments.  During  the  interval  between  an  Ipq(l)  com¬ 
mand  and  the  execution  of  Iprm,  the  next  job  in  line  may  have  become  active;  that  job  may  be  removed 
unintentionally  if  it  is  owned  by  you.  To  avoid  this,  supply  Iprm  with  the  job  number  to  remove  when  a 
critical  job  that  you  own  is  next  in  line. 

Only  the  super-user  can  remove  print  jobs  submitted  from  another  host. 
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NAME 

Ipstat  -  display  the  printer  status  information 
SYNOPSIS 

Ipstat  [  -d  ]  [  -r  ]  [  -s  ]  [  -t  ]  [  -a  [  /wf  ]  ]  [  -c  [  /wr  ]  ]  [  -0  [  list  ]  ]  [  -p  [  list  ]  ]  [  -u  [  list  ]  ] 

[-y[list]] 

DESCRIPTION 

Ipstat  prints  information  about  the  current  status  of  the  printer  spooling  system. 

If  no  options  are  given,  then  Ipstat  prints  the  status  of  all  requests  made  to  lp(l)  by  the  user.  When  the 
destination  printer  is  not  explicitly  specified,  the  value  of  the  LPDEST  environment  variable  is  used  by 
default.  If  LPDEST  is  not  defined,  then  the  value  of  the  PRINTER  environment  variable  is  used.  If 
PRINTER  is  not  defined  either,  then  the  system  default  printer  is  used.  Any  arguments  that  are  not  options 
are  assumed  to  be  request  ids  (as  returned  by  Ip).  Ipstat  prints  the  status  of  such  requests. 

OPTIONS 

The  options  below  may  appear  in  any  order  and  may  be  repeated  and  intermixed  with  other  arguments. 
Some  of  the  options  below  may  be  followed  by  an  optional  list  that  can  be  in  one  of  two  forms:  a  list  of 
items  separated  from  one  another  by  a  comma,  or  a  list  of  items  enclosed  in  double  quotes  and  separated 
from  one  another  by  a  comma  and/or  one  or  more  SPACE  characters.  For  example: 

~u"userl,  user2,  user3" 

The  omission  of  a  list  following  such  options  prints  all  information  relevant  to  the  option,  for  example: 
Ipstat  -o 

prints  the  status  of  all  output  requests. 

-d  Print  the  system  default  destination  for  output  requests. 

-r  Print  the  status  of  the  printer  request  scheduler 

-s  Print  a  status  summary,  including  the  status  of  the  line  printer  scheduler,  the  system  default 

destination,  a  list  of  class  names  and  their  members,  and  a  list  of  printers  and  their  associated 
devices. 

-t  Print  all  status  information. 

-a[/i.yr]  Print  acceptance  status  of  destinations  for  output  requests,  list  is  a  list  of  intermixed  printer 
names. 

-c[  list  ]  Print  class  names  and  their  members,  list  is  a  list  of  class  names. 

-o[ list]  Print  the  status  of  output  requests,  list  is  a  list  of  intermixed  printer  names,  class  names,  and 
request  ids. 

-p[list]  Print  the  status  of  printers,  /wf  is  a  list  of  printer  names. 

-u[  list]  Print  status  of  output  requests  for  users  on  the  default  printer,  list  is  a  list  of  login  names. 

-v[  list  ]  Print  the  names  of  printers  and  the  path  names  of  the  devices  associated  with  them,  list  is  a  list 

of  printer  names. 

FILES 

/usr/spool/lp 
SEE  ALSO 

lp(l),  Ipr(l),  Iprm(l),  lpc(8),  Ipd(8) 
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NAME 

Iptest  -  generate  lineprinter  ripple  pattern 
SYNOPSIS 

Iptest  [  length  [  count  ]  ] 

DESCRIPTION 

Iptest  writes  the  traditional  "ripple  test"  pattern  on  standard  output.  In  96  lines,  this  pattern  will  print  all  96 
printable  ASCII  characters  in  each  position.  While  originally  created  to  test  printers,  it  is  quite  useful  for 
testing  terminals,  driving  terminal  ports  for  debugging  purposes,  or  any  other  task  where  a  quick  supply  of 
random  data  is  needed. 

The  length  argument  specifies  the  output  line  length  if  the  default  length  of  79  is  inappropriate. 

The  count  argument  specifies  the  number  of  output  lines  to  be  generated  if  the  default  count  of  200  is  inap¬ 
propriate,  Note  that  if  count  is  to  be  specified,  length  must  be  also  be  specified. 
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NAME 

Is  “  list  the  contents  of  a  directory 
SYNOPSIS 

Is  [  -aAcCdfFgilLqrRstul  ]  filename  . . . 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/ls  [  -abcCdfFgilLmnopqrRstux  ]  . . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

For  each  filename  which  is  a  directory.  Is  lists  the  contents  of  the  directory;  for  each  filename  which  is  a 
file.  Is  repeats  its  name  and  any  other  information  requested.  By  default,  the  output  is  sorted  alphabetically. 
When  no  argument  is  given,  the  current  directory  is  listed.  When  several  arguments  are  given,  the  argu¬ 
ments  are  first  sorted  appropriately,  but  file  arguments  are  processed  before  directories  and  their  contents. 

In  order  to  determine  output  formats  for  the  -C,  -x,  and  -m  options,  /usr/Sbin/ls  uses  an  environment 
variable,  COLUMNS,  to  determine  the  number  of  character  positions  available  on  one  output  line.  If  this 
variable  is  not  set,  the  terminfo  database  is  used  to  determine  the  number  of  columns,  based  on  the 
environment  variable  TERM.  If  this  information  cannot  be  obtained,  80  columns  are  assumed. 

Permissions  Field 

The  mode  printed  under  the  —1  option  contains  10  characters  interpreted  as  follows.  If  the  first  character  is: 

d  entry  is  a  directory; 
b  entry  is  a  block-type  special  file; 
c  entry  is  a  character-type  special  file; 

I  entry  is  a  symbolic  link; 

p  entry  is  a  FIFO  (also  known  as  “named  pipe”)  special  file; 
s  entry  is  an  AF_UNIX  address  family  socket,  or 

-  entry  is  a  plain  file. 

The  next  9  characters  are  interpreted  as  three  sets  of  three  bits  each.  The  first  set  refers  to  owner  permis¬ 
sions;  the  next  refers  to  permissions  to  others  in  the  same  user-group;  and  the  last  refers  to  all  others. 
Within  each  set  the  three  characters  indicate  permission  respectively  to  read,  to  write,  or  to  execute  the  file 
as  a  program.  For  a  directory,  “execute”  permission  is  interpreted  to  mean  permission  to  search  the  direc¬ 
tory.  The  permissions  are  indicated  as  follows: 

r  the  file  is  readable; 
w  the  file  is  writable; 

X  the  file  is  executable; 

—  the  indicated  permission  is  not  granted. 

The  group-execute  permission  character  is  given  as  s  if  the  file  has  the  set-group-id  bit  set;  likewise  the 
owner-execute  permission  character  is  given  as  s  if  the  file  has  the  set-user-id  bit  set 

The  last  character  of  the  mode  (normally  x  or  *-’)  is  t  if  the  1000  bit  of  the  mode  is  on.  See  chmod(lV) 
for  the  meaning  of  this  mode.  The  indications  of  set-ID  and  1000  bits  of  the  mode  are  capitalized  (S  and  T 
respectively)  if  the  corresponding  execute  permission  is  not  set. 

When  the  sizes  of  the  files  in  a  directory  are  listed,  a  total  count  of  blocks,  including  indirect  blocks  is 
printed. 

OPTIONS 

-a  List  all  entries;  in  the  absence  of  this  option,  entries  whose  names  begin  with  a  are  not  listed 
(except  for  the  super-user,  for  whom  Is,  but  not  /usr/5bin/Is,  normally  prints  even  files  that  begin 
with  a  */)‘ 

-A  (Is  only)  Same  as  -a,  except  that  and  are  not  listed. 
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-c 

-C 

-d 

-f 

-F 


-i 

-I 


-L 

-q 

— r 
-R 

“S 

-t 

-u 

-1 

SYSTEM  V 
-b 


-o 

-P 

— X 


Use  time  of  last  edit  (or  last  mode  change)  for  sorting  or  printing. 

Force  multi-column  output,  with  entries  sorted  down  the  columns;  for  Is,  this  is  the  default  when 
output  is  to  a  terminal. 

If  argument  is  a  directory,  list  only  its  name  (not  its  contents);  often  used  with  -1  to  get  the  status 
of  a  directory. 

Force  each  argument  to  be  interpreted  as  a  directory  and  list  the  name  found  in  each  slot.  This 
option  turns  off  —1,  — t,  — s,  and  — r,  and  turns  on  —a;  the  order  is  the  order  in  which  entries  appear 
in  the  directory. 


Mark  directories  with  a  trailing  slash  (7’),  executable  files  with  a  trailing  asterisk  (*♦’),  symbolic 
links  with  a  trailing  at-sign  (‘(S)’),  and  AF  UNIX  address  family  sockets  with  a  trailing  equals  sign 
(=’). 


For  Is,  show  the  group  ownership  of  the  file  in  a  long  output  For  /usr/5bin/Is,  print  a  long  listing, 
the  same  as  -1,  except  that  the  owner  is  not  printed. 

For  each  file,  print  the  i-number  in  the  first  column  of  the  report. 

List  in  long  format,  giving  mode,  number  of  links,  owner,  size  in  bytes,  and  time  of  last 
modification  for  each  file.  If  the  file  is  a  special  file  the  size  field  will  instead  contain  the  major 
and  minor  device  numbers.  If  the  time  of  last  modification  is  greater  than  six  months  ago,  it  is 
shown  in  the  format  'month  date  year";  files  modified  within  six  months  show  'month  date  time". 
If  the  file  is  a  symbolic  link  the  pathname  of  the  linked-to  file  is  printed  preceded  by  ‘ — >’. 
/usr/Sbin/Is  will  print  the  group  in  addition  to  the  owner. 

If  argument  is  a  symbolic  link,  list  the  file  or  directory  the  link  references  rather  than  the  link 
itself. 


Display  non-graphic  characters  in  filenames  as  the  character  ?;  for  Is,  this  is  the  default  when  out¬ 
put  is  to  a  terminal. 

Reverse  the  order  of  sort  to  get  reverse  alphabetic  or  oldest  first  as  appropriate. 

Recursively  list  subdirectories  encountered. 

Give  size  of  each  file,  including  any  indirect  blocks  used  to  map  the  file,  in  kilobytes  (Is)  or  512- 
byte  blocks  (/usr/5bin/Is). 

Sort  by  time  modified  (latest  first)  instead  of  by  name. 

Use  time  of  last  access  instead  of  last  modification  for  sorting  (with  the  -t  option)  and/or  printing 
(with  the  -1  option). 

(Is  only)  Force  one  entry  per  line  output  format;  this  is  the  default  when  output  is  not  to  a  terminal. 
OPTIONS 

Force  printing  of  non-graphic  characters  to  be  in  the  octal  \ddd  notation. 

Stream  output  format;  the  file  names  are  printed  as  a  list  separated  by  commas,  with  as  many 
entries  as  possible  printed  on  a  line. 

The  same  as  -1,  except  that  the  owner’s  UID  and  group’s  GID  numbers  are  printed,  rather  than  the 
associated  character  strings. 

The  same  as  -I,  except  that  the  group  is  not  printed. 

Put  a  slash  (7’)  after  each  filename  if  that  file  is  a  directory. 

Multi-column  output  with  entries  sorted  across  rather  than  down  the  page. 


ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  Is.  On  entry  to  Is,  these  environment  variables  are  checked  in  the  following  order:  LC_CTYPE, 
LANG,  and  LC_defauIt.  When  a  valid  value  is  found,  remaining  environment  variables  for  character 
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classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current  valid  charac¬ 
ter  classification  rules  of  LC^CTYPE.  When  none  of  the  values  is  valid,  the  shell  character  classification 
defaults  to  the  POSDC.l  “C"  locale. 

FILES 

/etc/passwd  to  get  user  ID’s  for  ‘Is  -1’  and  ‘Is  -o’. 

/etc/group  to  get  group  ID  for  ‘Is  -g’  and  ‘/usr/Sbin/ls  -1’. 

/usr/share/lib/terminfo/* 

to  get  terminal  information  for  /usr/5bin/ls. 

SEE  ALSO 

chmod(lV) 

BUGS 

NEWLINE  and  TAB  are  considered  printing  characters  in  filenames. 

The  output  device  is  assumed  to  be  80  columns  wide. 

The  option  setting  based  on  whether  the  output  is  a  teletype  is  undesirable  as  ‘Is  -s’  is  much  different  than 
‘Is  -s  I  Ipr’.  On  the  other  hand,  not  doing  this  setting  would  make  old  shell  scripts  which  used  Is  almost 
certain  losers. 

None  of  the  above  apply  to  /usr/5bin/ls. 

Unprintable  characters  in  file  names  may  confuse  the  columnar  output  options. 
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NAME 

Isw  ~  list  TFS  whiteout  entries 

SYNOPSIS 

Isw  filename  . . . 

DESCRIPTION 

For  each  filename  that  is  a  directory,  Isw  lists  the  whiteout  entries  in  that  directory.  These  whiteout  entries 
are  created  by  the  translucent  file  service  See  tfs(4S). 

SEE  ALSO 

unwhiteout(l),  tfs(4S),  mount Jfs(8),  tfsd(8) 
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NAME 

m4  -  macro  language  processor 

SYNOPSIS 

m4  [filename  ] ... 

SYSTEM  V  SYNOPSIS 

/iisr/5biii/in4  [  — es  ]  [  —Bint  ]  [  —Mint  ]  [  Sint  ]  [  —Tint  ]  [  —l}name=val  ]  [  —Uname  ]  [filename  ]. . . 
AVAILABILITY 

The  System  V  version  of  this  command  is  available  widi  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

m4  is  a  macro  processor  intended  as  a  front  end  for  Ratfor,  C,  and  other  languages.  Each  of  the  argument 
files  is  processed  in  order;  if  there  are  no  files,  or  if  a  file  name  is  the  standard  input  is  read.  The  pro¬ 
cessed  text  is  written  on  the  standard  output. 

Macro  calls  have  the  form; 

name(argumentl[,  argument! , . . .,]  argument n) 

The  ‘(’  must  immediately  follow  the  name  of  the  macro.  If  the  name  of  a  defined  macro  is  not  followed  by 
a  W  it  is  interpreted  as  a  call  of  the  macro  with  no  arguments.  Potential  macro  names  consist  of  letters, 
digits,  and  (underscores)  where  the  first  character  is  not  a  digit. 

Leading  unquoted  SPACE,  TAB,  and  NEWLINE  characters  are  ignored  while  collecting  arguments.  Left  and 
right  single  quotes  (‘  ’)  are  used  to  quote  strings.  The  value  of  a  quoted  string  is  the  string  stripped  of  the 
quotes. 

When  a  macro  name  is  recognized,  the  arguments  are  collected  by  searching  for  a  matching  right 
parenthesis.  If  fewer  arguments  are  supplied  than  are  in  the  macro  definition,  the  trailing  arguments  are 
taken  to  be  NULL.  Macro  evaluation  proceeds  normally  during  the  collection  of  the  arguments,  and  any 
commas  or  right  parentheses  which  happen  to  turn  up  within  the  value  of  a  nested  call  are  as  effective  as 
those  in  the  original  input  text.  After  argument  collection,  the  value  of  the  macro  is  pushed  back  onto  the 
input  stream  and  rescanned. 

SYSTEM  V  OPTIONS 

The  options  and  their  effects  are  as  follows; 

-e  Operate  interactively.  Interrupts  are  ignored  and  the  output  is  unbuffered. 

-s  Enable  line  sync  output  for  the  C  preprocessor  (#line  . . . ) 

-Bint  Change  the  size  of  the  push-back  and  argument  collection  buffers  from  the  default  of  4,096. 

-Hint  Change  the  size  of  the  symbol  table  hash  array  from  the  default  of  199.  The  size  should  be  prime. 

-Sint  Change  the  size  of  the  call  stack  from  the  default  of  100  slots.  Macros  take  three  slots,  and  non¬ 
macro  arguments  take  one. 

-Tint  Change  the  size  of  the  token  buffer  from  the  default  of  512  bytes. 

To  be  effective,  these  flags  must  appear  before  any  file  names  and  before  any  ~D  or  -U  flags; 
~Dname[=val\ 

Define  filename  to  be  val  or  to  be  NULL  in  va/’s  absence. 

-Uname 

Undefine  name. 

USAGE 

Built-In  Macros 

m4  makes  available  the  following  built-in  macros.  They  may  be  redefined,  but  once  this  is  done  the  origi¬ 
nal  meaning  is  lost.  Their  values  are  NULL  unless  otherwise  stated. 
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define  The  second  argument  is  installed  as  the  value  of  the  macro  whose  name  is  the  first  argu¬ 

ment.  Each  occurrence  of  $n  in  the  replacement  text,  where  n  is  a  digit,  is  replaced  by  the 
n’th  argument.  Argument  0  is  the  name  of  the  macro;  missing  arguments  are  replaced  by 
the  NULL  string. 

undefine  Remove  the  definition  of  the  macro  named  in  the  argument. 

ifdef  If  the  first  argument  is  defined,  the  value  is  the  second  argument,  otherwise  the  third.  If 

there  is  no  third  argument,  the  value  is  NULL.  The  word  mix  is  predefined. 

changequote  Change  quote  characters  to  the  first  and  second  arguments,  changequote  without  arguments 
restores  the  original  values  (that  is,  ‘  ’)• 

divert  m4  maintains  10  output  streams,  numbered  0-9.  The  final  output  is  the  concatenation  of  the 

streams  in  numerical  order,  initially  stream  0  is  the  current  stream.  The  divert  macro 
changes  the  current  output  stream  to  the  (digit-string)  argument  Output  diverted  to  a  stream 
other  than  0  through  9  is  discarded, 

undivert  Display  immediate  output  of  text  from  diversions  named  as  arguments,  or  all  diversions  if 
no  argument.  Text  may  be  undiverted  into  another  diversion.  Undiverting  discards  the 
diverted  text. 


divnum 

dnl 

ifelse 


incr 

eval 

len 

index 

substr 

translit 

include 

sinclude 

syscmd 

maketemp 


Return  the  value  of  the  current  output  stream. 

Read  and  discard  characters  up  to  and  including  the  next  NEWLINE. 

Has  three  or  more  arguments.  If  the  first  argument  is  the  same  string  as  the  second,  then  the 
value  is  the  third  argument.  If  not,  and  if  there  are  more  than  four  arguments,  the  process  is 
repeated  with  arguments  4,  5,  6,  7  and  so  on.  Otherwise,  the  value  is  either  the  last  string 
not  used  by  the  above  process,  or,  if  it  is  not  present,  NULL. 

Return  the  value  of  the  argument  incremented  by  1.  The  value  of  the  argument  is  calculated 
by  interpreting  an  initial  digit-string  as  a  decimal  number. 

Evaluate  the  argument  as  an  arithmetic  expression,  using  32-bit  arithmetic.  Operators 
include  (exponentiation);  relationals;  parentheses. 

Return  the  number  of  characters  in  the  argument. 

Return  the  position  in  the  first  argument  where  the  second  argument  begins  (zero  origin),  or 
-1  if  the  second  argument  does  not  occur. 

Return  a  substring  of  the  first  argument.  The  second  argument  is  a  zero  origin  number 
selecting  the  first  character;  the  third  argument  indicates  the  length  of  the  substring.  A  miss¬ 
ing  third  argument  is  taken  to  be  large  enough  to  extend  to  the  end  of  the  first  string. 

Transliterate  the  characters  in  the  first  argument  from  the  set  given  by  the  second  argument 
to  the  set  given  by  the  third.  No  abbreviations  are  permitted. 

Return  the  contents  of  the  file  named  in  the  argument. 

Is  similar  to  include,  except  that  it  says  nothing  if  the  file  is  inaccessible. 

Execute  the  system  command  given  in  the  first  argument.  No  value  is  returned. 

Fill  in  a  string  of  XXXXX  in  the  argument  with  the  current  process  ID. 


errprint  Print  the  argument  on  the  diagnostic  output  file. 


dumpdef  Print  current  names  and  definitions,  for  the  named  items,  or  for  all  if  no  arguments  are 
given. 


SYSTEM  V  USAGE 

In  the  System  V  version  of  m4,  the  following  built-in  macros  have  added  capabilities. 
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Built-In  Macros 
define 


changequote 

eval 


The  System  V 
defn 

pushdef 

popdef 

shift 


changecom 


deer 

sysval 

ni4exit 

ni4wrap 

traceon 

traceoff 

SEE  ALSO 

cc(lV) 


*$#’  is  replaced  by  the  number  of  arguments;  $*  is  replaced  by  a  list  of  all  the  arguments 
separated  by  commas;  $@  is  like  but  each  argument  is  quoted  (with  the  current 
quotes). 

Change  quote  symbols  to  the  first  and  second  arguments.  The  symbols  may  be  up  to  five 
characters  long. 

Additional  operators  include  bitwise  *&’,  ‘|  and  Octal,  decimal  and  hex  numbers 
may  be  specified  as  in  C.  The  second  argument  specifies  the  radix  for  the  result;  the  default 
is  10.  The  third  argument  may  be  used  to  specify  the  minimum  number  of  digits  in  the 
result. 

version  of  m4  makes  available  the  following  additional  built-in  macros. 

Return  the  quoted  definition  of  the  argument(s).  It  is  useful  for  renaming  macros,  especially 
built-ins. 

Like  define,  but  saves  any  previous  definition. 

Remove  current  definition  of  the  argument(s),  exposing  the  previous  one,  if  any. 

Return  all  but  the  first  argument.  The  other  arguments  are  quoted  and  pushed  back  with 
commas  in  between.  The  quoting  nullifies  the  effect  of  the  extra  scan  that  will  subsequently 
be  performed. 

Change  left  and  right  comment  markers  from  the  default  #  and  NEWUNE.  With  no  argu¬ 
ments,  the  comment  mechanism  is  effectively  disabled.  With  one  argument,  the  left  marker 
becomes  the  argument  and  the  right  marker  becomes  NEWLINE.  With  two  arguments,  both 
markers  are  affected.  Comment  markers  may  be  up  to  five  characters  long. 

Return  the  value  of  the  argument  decremented  by  1. 

Return  code  from  the  last  call  to  sysemd. 

Exit  immediately  from  m4.  Argument  1,  if  given,  is  the  exit  code;  the  default  is  0. 

Argument  1  will  be  pushed  back  at  final  EOF.  For  example,  ‘m4vnrap(“cleanup(  )”)*. 

With  no  arguments,  turn  on  tracing  for  all  macros  (including  built-ins).  Otherwise,  turn  on 
tracing  for  named  macros. 

Turn  off  trace  globally  and  for  any  macros  specified.  Macros  specifically  traced  by  traceon 
can  be  untraced  only  by  specific  calls  to  traceoff. 


m4 — A  Macro  Processor,  in  Programming  Utilities  and  Libraries 

NOTES 

While  the  compiler  allows  8-bit  strings  and  comments,  8-bits  are  not  allowed  anywhere  else.  The  cc(lV) 
command  does  not  generate  or  support  8-bit  symbol  names  because,  until  ANSI  C,  non-ASCn  support  was 
not  expected.  The  ANSI  C  specification  now  suggests  that  string  literals  and  comments  can  contain  any 
characters  from  any  character  code  set. 
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NAME 

mach  -  display  the  processor  type  of  the  current  host 

SYNOPSIS 

mach 

DESCRIPTION 

The  mach  command  displays  the  processor-type  of  the  current  Sun  host. 

SEE  ALSO 

arch(l),  machid(l) 
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NAME 

machid,  sun,  iAPX286,  m68k,  pdpll,  spare,  u3b,  u3b2,  u3b5,  u3bl5,  vax,  i386  ~  return  a  true  exit  status  if 
the  processor  is  of  the  indicated  type 

SYNOPSIS 

sun 

iAPX286 

m68k 

pdpll 

Sparc 

u3b 

u3b2 

u3b5 

u3bl5 

vax 

i386 

DESCRIPTION 

The  following  commands  will  return  a  true  value  (exit  code  of  0)  if  you  are  on  a  processor  that  the  com¬ 
mand  name  indicates. 

sun  True  if  you  are  on  a  Sun  system. 

iAPX286  True  if  you  are  on  a  computer  using  an  iAPX286  processor. 

1386  True  if  you  are  on  a  computer  using  an  iAPX386  processor. 

m68k  True  if  you  are  on  a  computer,  such  as  a  Sun-3  or  a  Sun-3x,  using  an  M68000-family 

processor. 

pdpll  True  if  you  are  on  a  PDP- 1 1 . 

Sparc  True  if  you  are  on  a  computer,  such  as  a  Sun-4,  using  a  SPARC-family  processor. 

u3b  True  if  you  are  on  a  3B20S  computer. 

u3b2  True  if  you  are  on  a  3B2  computer. 

u3b5  True  if  you  are  on  a  3B5  computer. 

u3bl5  True  if  you  are  on  a  3B 15  computer. 

vax  True  if  you  are  on  a  VAX. 

The  commands  that  do  not  apply  will  return  a  false  (non-zero)  value.  These  commands  are  often  used 
within  make(l)  makefiles  and  shell  procedures  to  increase  portability. 

SEE  ALSO 

arch(l),  mach(l),  make(l),  sh(l),  test(lV),  true(l) 
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NAME 

mail.  Mail  -  read  or  send  mail  messages 
SYNOPSIS 

Mail  [  -deHinNUv  ]  [  -f  [filename  I  +f older  ]][~Tfil€][-u  user  ] 
Mail  [  -dFinUv  ]  [  -h  number  ]  [  -r  address  ]  [  -s  subject  ]  recipient . . , 

/usr/ucb/mail . . . 


DESCRIPTION 

mail  is  a  comfortable,  flexible,  interactive  program  for  composing,  sending  and  receiving  electronic  mes¬ 
sages,  While  reading  messages,  mail  provides  you  with  commands  to  browse,  display,  save,  delete,  and 
respond  to  messages.  While  sending  mail,  mail  allows  editing  and  reviewing  of  messages  being  com¬ 
posed,  and  the  inclusion  of  text  from  files  or  other  messages. 

Incoming  mail  is  stored  in  the  system  mailbox  for  each  user.  This  is  a  file  named  after  the  user  in 
/var/spool/mail.  mail  normally  looks  in  this  file  for  incoming  messages,  but  you  can  use  the  MAIL 
environment  variable  to  have  it  look  in  a  different  file.  When  you  read  a  message,  it  is  marked  to  be  moved 
to  a  secondary  file  for  storage.  This  secondary  file,  called  the  mbox,  is  normally  the  file  mbox  in  your  home 
directory.  This  file  can  also  be  changed  by  setting  the  MBOX  environment  variable.  Messages  remain  in 
the  mbox  file  until  deliberately  removed. 


OPTIONS 

If  no  recipient  is  specified,  mail  attempts  to  read  messages  from  the  system  mailbox. 


-d 

-e 

-F 


Turn  on  debugging  output.  (Neither  particularly  interesting  nor  recommended.) 

Test  for  presence  of  mail.  If  there  is  no  mail,  mail  prints  nothing  and  exits  (with  a  suc¬ 
cessful  return  code). 

Record  the  message  in  a  file  named  after  the  first  recipient.  Override  the  record  variable, 
if  set. 


-H 
-i 
— n 

-N 

-U 


Print  header  summary  only. 

Ignore  interrupts  (as  with  the  ignore  variable). 

Do  not  initialize  from  the  system  default  MaiLrc  file. 

Do  not  print  initial  header  summary. 

Convert  uucp  style  addresses  to  Internet  standards.  Overrides  the  conv  environment  vari¬ 
able. 


~v 

-f  [filename] 

-f  +folder 

-h  number 

-r  address 
-s  subject 
-Tfile 

-u  user 


Pass  the  -v  flag  to  sendmail(8). 

Read  messages  from  filename  instead  of  system  mailbox.  If  no  filename  is  specified,  the 
mbox  is  used. 

Use  the  file  folder  in  the  folder  directory  (same  as  the  folder  command).  The  name  of  this 
directory  is  listed  in  the  folder  variable. 

The  number  of  network  “hops”  made  so  far.  This  is  provided  for  network  software  to 
avoid  infinite  delivery  loops. 

Pass  address  to  network  delivery  software.  All  tilde  (~)  commands  are  disabled. 

Set  the  Subject  header  field  to  subject. 

Print  the  contents  of  the  article-id  fields  of  all  messages  that  were  read  or  deleted  on  file 
(for  the  use  of  network  news  programs  if  available). 

Read  user's  system  mailbox.  This  is  only  effective  if  user's  system  mailbox  is  not  read 
protected. 
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USAGE 

Refer  to  SunOS  Users  Guide:  Getting  Started  for  tutorial  information  about  mail. 

Starting  Mail 

As  it  starts,  mail  reads  commands  from  a  system- wide  file  (/usr/Iib/Mail.rc)  to  initialize  certain  variables, 
then  it  reads  from  a  private  start-up  file  called  the  .mailrc  file  (it  is  normally  the  file  .mailrc  in  your  home 
directory,  but  can  be  changed  by  setting  the  MAILRC  environment  variable)  for  your  personal  commands 
and  variable  settings.  Most  mail  commands  are  legal  inside  start-up  files.  The  most  common  uses  for  this 
file  are  to  set  up  initial  display  options  and  alias  lists.  The  following  commands  are  not  legal  in  the  start-up 
file:  !,  Copy,  edit,  followup,  Followup,  hold,  mail,  preserve,  reply,  Reply,  replyall,  replysender,  shell, 
and  visual.  Any  errors  in  the  start-up  file  cause  the  remaining  lines  in  that  file  to  be  ignored. 

You  can  use  the  mail  command  to  send  a  message  directly  by  including  names  of  recipients  as  arguments 
on  the  command  line.  When  no  recipients  appear  on  the  mail  command  line,  it  enters  command  mode, 
from  which  you  can  read  messages  sent  to  you.  If  you  list  no  recipients  and  have  no  messages,  mail  prints 
the  message:  ‘No  mail  for  username"  and  exits. 

When  in  command  mode  (while  reading  messages),  you  can  send  messages  using  the  mail  command. 
Sending  Mail 

While  you  are  composing  a  message  to  send,  mail  is  in  input  mode.  If  no  subject  is  specified  as  an  argu¬ 
ment  to  the  command  a  prompt  for  the  subject  is  printed.  After  entering  the  subject  line,  mail  enters  input 
mode  to  accept  the  text  of  your  message  to  send. 

As  you  type  in  the  message,  mail  stores  it  in  a  temporary  file.  To  review  or  modify  the  message,  enter  the 
appropriate  tilde  escapes,  listed  below,  at  the  beginning  of  an  input  line. 

To  indicate  that  the  message  is  ready  to  send,  type  a  dot  (or  EOF  character,  normally  CTRL-D  )  on  a  line  by 
itself,  mail  submits  the  message  to  sendmail(8)  for  routing  to  each  recipient. 

Recipients  can  be; 

•  local  usernames 

•  Internet  addresses  of  the  form: 

name@domain 

•  uucp(lC)  addresses  of  the  form: 

[hostl. .  .hostl]host\username 

•  filenames  for  which  you  have  write  permission 

•  alias  groups 

If  the  name  of  the  recipient  begins  with  a  pipe  symbol  ( | ),  the  remainder  of  the  name  is  taken  as  a  shell 
command  to  pipe  the  message  through.  This  provides  an  automatic  interface  with  any  program  that  reads 
the  standard  input,  such  as  Ipr(l)  to  record  outgoing  mail  on  paper.  An  alias  group  is  the  name  of  a  list  of 
recipients  that  is  set  by  the  alias  command,  taken  from  the  host’s  /etc/aliases  file,  or  taken  from  the  Net¬ 
work  Information  Service  (NIS)  aliases  domain.  See  aliases(5)  for  more  information  about  mail  addresses 
and  aliases. 

Tilde  Escapes 

The  following  tilde  escape  commands  can  be  used  when  composing  messages  to  send.  Each  must  appear  at 
the  beginning  of  an  input  line.  The  escape  character  (~),  can  be  changed  by  setting  a  new  value  for  the 
escape  variable.  The  escape  character  can  be  entered  as  text  by  typing  it  twice. 

-I  [shell-command] 

Escape  to  the  shell.  If  present,  run  shell-command. 

Simulate  EOF  (terminate  message  input). 
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mail-command 

mail-command 

Perform  the  indicated  mail  command.  Valid  only  when  sending  a  message  while  reading  mail. 

~?  Print  a  summary  of  tilde  escapes. 

~A  Insert  the  autograph  string  Sign  into  the  message. 

-a  Insert  the  autograph  string  sign  into  the  message. 

~b  name  . . . 

Add  the  names  to  the  blind  carbon  copy  (Bcc)  list.  This  is  like  the  carbon  copy  (Cc)  list,  except 
that  the  names  in  the  Bcc  list  are  not  shown  in  the  header  of  the  mail  message. 

~c  name . . . 

Add  the  names  to  the  carbon  copy  (Cc)  list. 

~d  Read  in  the  dead. letter  file.  The  name  of  this  file  is  listed  in  the  variable  DEAD. 

~e  Invoke  the  editor  to  edit  the  message.  The  name  of  the  editor  is  listed  in  the  EDITOR  variable. 

The  default  editor  is  ex(l). 

~f  [message-list] 

Forward  the  listed  messages,  or  the  current  message  being  read.  Valid  only  when  sending  a  mes¬ 
sage  while  reading  mail;  the  messages  are  inserted  without  alteration  (as  opposed  to  the  -m 
escape). 

~h  Prompt  for  the  message  header  lines:  Subject,  To,  Cc,  and  Bcc.  If  the  header  line  contains  text, 
you  can  edit  the  text  by  backspacing  over  it  and  retyping. 

~i  variable 

Insert  the  value  of  the  named  variable  into  the  message. 

-m  [message-list] 

Insert  text  from  the  specified  messages,  or  the  current  message,  into  the  letter.  Valid  only  when 
sending  a  message  while  reading  mail;  the  text  the  message  is  shifted  to  the  right,  and  the  string 
contained  in  the  indentprefix  variable  is  inserted  as  the  leftmost  characters  of  each  line.  If 
indentprefix  is  not  set,  a  TAB  character  is  inserted  into  each  line. 

~p  Print  the  message  being  entered. 

~q  Quit  from  input  mode  by  simulating  an  interrupt.  If  the  body  of  the  message  is  not  empty,  the  par¬ 
tial  message  is  saved  in  the  dead.letter  file. 

-r  filename 
~<  filename 
~<!  shell-command 

Read  in  text  from  the  specified  file  or  the  standard  output  of  the  specified  shell-command. 

~s  subject 

Set  the  subject  line  to  subject. 

~t  name  . . . 

Add  each  name  to  the  list  of  recipients. 

~v  Invoke  a  visual  editor  to  edit  the  message.  The  name  of  the  editor  is  listed  in  the  VISUAL  vari¬ 
able.  The  default  visual  editor  is  vi(l). 

~w  filename 

Write  the  message  text  onto  the  given  file,  without  the  header. 

~x  Exit  as  with  ~q  but  do  not  save  the  message  in  the  dead.letter  file. 

~j  shell-command 

Pipe  the  body  of  the  message  through  the  given  shell-command.  If  shell-command  returns  a  suc¬ 
cessful  exit  status,  the  output  of  the  command  replaces  the  message. 


w 
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Reading  Mail 

When  you  enter  command  mode  in  order  to  read  your  messages,  mail  displays  a  header  summary  of  the 
first  several  messages,  followed  by  a  prompt  for  one  of  the  commands  listed  below.  The  default  prompt  is 
the  &  (ampersand  character). 

Message  are  listed  and  referred  to  by  number.  There  is,  at  any  time,  a  current  message,  which  is  marked 
by  a  >  in  the  header  summary.  For  commands  that  take  an  optional  list  of  messages,  if  you  omit  a  message 
number  as  an  argument,  the  command  applies  to  the  current  message. 

A  message-list  is  a  list  of  message  specifications,  separated  by  SPACE  characters,  which  may  include: 


. 

The  current  message. 

n 

Message  number  n. 

■* 

The  first  undeleted  message. 

$ 

The  last  message. 

+ 

The  next  undeleted  message. 

- 

The  previous  undeleted  message. 

* 

All  messages. 

n-m 

An  inclusive  range  of  message  numbers. 

user 

All  messages  from  user. 

/string 

All  messages  with  string  in  the  subject  line  (case  ignored). 

:c 

All  messages  of  type  c,  where  c  is  one  of: 

d  deleted  messages 
n  new  messages 

o  old  messages 

r  read  messages 

u  unread  messages 

Note:  the  context  of  the  command  determines  whether  this  type  of  message  specification 
makes  sense. 

Additional  arguments  are  treated  as  strings  whose  usage  depends  on  the  command  involved.  Filenames, 

where  expected,  are  expanded  using  the  normal  shell  filename-substitution  mechanism. 

Special  characters,  recognized  by  certain  commands,  are  documented  with  those  commands. 

Commands 

While  in  command  mode,  if  you  type  in  an  empty  command  line  (a  RETURN  or  NEWLINE  only),  the  print 

command  is  assumed.  The  following  is  a  complete  list  of  mail  commands: 

!  shell-command  Escape  to  the  shell.  The  name  of  the  shell  to  use  is  listed  in  the  SHELL  variable, 

#  arguments  Null  command.  This  may  be  used  as  if  it  were  a  comment  in  ,mailrc  files,  but  note 

that  it  must  be  separated  from  its  arguments  (commentary)  by  white  space. 

=  Print  the  current  message  number. 

?  Print  a  summary  of  commands. 

alias  [alias  recipient . . .] 

group  [alias  recipient . . .] 

Declare  an  alias  for  the  given  list  of  recipients.  The  list  will  be  substituted  when  the 
alias  is  used  as  a  recipient  while  sending  mail.  When  put  in  the  .mailrc  file,  this 
command  provides  you  with  a  record  of  the  alias.  With  no  arguments,  the  command 
displays  the  list  of  defined  aliases. 

alternates  name  . . .  Declare  a  list  of  alternate  names  for  your  login.  When  responding  to  a  message, 
these  names  are  removed  from  the  list  of  recipients  for  the  response.  With  no  argu¬ 
ments,  alternates  prints  the  current  list  of  alternate  names. 
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cd[  directory] 

chdir  [directory]  Change  directory.  If  directory  is  not  specified,  $HOME  is  used, 
copy  [message -list]  [filename] 

Copy  messages  to  the  file  without  marking  the  messages  as  saved.  Otherwise 
equivalent  to  the  save  command. 

Copy  [message-list]  Save  the  specified  messages  in  a  file  whose  name  is  derived  from  the  author  of  the 
message  to  be  saved,  without  marking  the  messages  as  saved.  Otherwise  equivalent 
to  the  Save  command. 

delete  [message-list]  Delete  messages  from  the  system  mailbox.  If  the  variable  autoprint  is  set,  print  the 
message  following  the  last  message  deleted. 

discard  [header-field. . .] 
ignore  [header-field. . .] 

Suppress  printing  of  the  specified  header  fields  when  displaying  messages  on  the 
screen,  such  as  “Status"  and  “Received”.  The  fields  are  included  when  the  message 
is  saved  unless  the  variable  alwaysignore  is  set.  The  Print  and  Type  commands 
display  all  header  fields,  ignored  or  not. 

dp  [message-list] 
dt  [message-list] 

Delete  the  specified  messages  from  the  system  mailbox,  and  print  the  message  after 
the  last  one  deleted.  Equivalent  to  a  delete  command  followed  by  a  print  command. 

echo  [string  ...]  Echo  the  given  strings  (like  echo(lV)). 

edit  [message-list]  Edit  the  given  messages.  The  messages  are  placed  in  a  temporary  file  and  the  EDI* 
TOR  variable  is  used  to  get  the  name  of  the  editor.  The  default  editor  is  ex(l). 

exit 

xit  Exit  from  mail  without  changing  the  system  mailbox.  No  messages  are  saved  in  the 

mbox  (see  also  quit). 

file  [filename] 

folder  [filename]  Quit  from  the  current  mailbox  file  and  read  in  the  named  mailbox  file.  Several  spe¬ 
cial  characters  are  recognized  when  used  as  file  names: 

%  Your  system  mailbox. 

%user  The  system  mailbox  for  user. 

#  The  previous  mail  file. 

&  Your  mbox  file  (of  messages  previously  read). 

^filename  The  named  file  in  the  folder  directory  (listed  in  the  folder  vari¬ 
able). 

With  no  arguments,  file  prints  the  name  of  the  current  mail  file,  and  the  number  of 
messages  and  characters  it  contains. 

folders  Print  the  name  of  each  mail  file  in  the  folder  directory  (listed  in  the  folder  variable). 

followup  [message]  Respond  to  a  message,  recording  the  response  in  a  file,  name  of  which  is  derived 
from  the  author  of  the  message  (overrides  the  record  variable,  if  set).  See  also  the 
Followup,  Save,  and  Copy  commands  and  the  outfolder  variable. 

Followup  [message-list] 

Respond  to  the  first  message  in  the  message  list,  sending  the  message  to  the  author  of 
each  message  in  the  list.  The  subject  line  is  taken  from  the  first  message,  and  the 
response  is  recorded  in  a  file,  the  name  of  which  is  derived  from  the  author  of  the 
first  message  (overrides  the  record  variable,  if  set).  See  also  the  followup,  Save,  and 
Copy  commands  and  the  outfolder  variable, 

from  [message-list]  Print  the  header  summary  for  the  indicated  messages  or  the  current  message. 
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group  alias  name  . . .  Same  as  the  alias  command. 

headers  [message]  Print  the  page  of  headers  that  includes  the  message  specified,  or  the  current  message. 

The  screen  variable  sets  the  number  of  headers  per  page.  See  also  the  z  command. 

help  Print  a  summary  of  commands. 

hold  [message-list] 
preserve  [message -list] 

Hold  the  specified  messages  in  the  system  mailbox. 

if  s  Ir  It 
mail-command 

else 

mail-command 

endif  Conditional  execution,  where  s  will  execute  following  mail-command  up  to  an  else 

or  endif,  if  the  program  is  in  send  mode,  r  executes  the  mail-command  only  in 
receive  mode,  and  t  executes  the  mail-command  only  if  mail  is  being  run  from  a  ter¬ 
minal.  Useful  primarily  in  the  .mailrc  file. 

ignore  [header-field. . .  ] 

Same  as  the  discard  command. 

inc  Incorporate  messages  that  arrive  while  you  are  reading  the  system  mailbox.  The 

new  messages  are  added  to  the  message  list  in  the  current  mail  session.  This  com¬ 
mand  does  not  commit  changes  made  during  the  session,  and  prior  messages  are  not 
renumbered. 

list  Prints  all  commands  available.  No  explanation  is  given, 

load  [message]  filename 

Load  the  specified  message  from  the  name  file,  filename  should  contain  a  single 
mail  message  including  mail  headers  (as  saved  by  the  save  command). 

mail  recipient . . .  Mail  a  message  to  the  specified  recipients. 

mbox  [message-list]  Arrange  for  the  given  messages  to  end  up  in  the  standard  mbox  file  when  mail  ter¬ 
minates  normally.  See  also  the  exit  and  quit  commands. 

new  [message-list] 

New  [message-list] 
unread  [message-list] 

Unread  [message-list] 

Take  a  message  list  and  mark  each  message  as  not  having  been  read. 

next  message  Go  to  next  message  matching  message.  A  message-list  can  be  given  instead  of  mes¬ 

sage,  but  only  first  valid  message  in  the  list  is  used.  (This  can  be  used,  for  instance, 
to  jump  to  the  next  message  from  a  specific  user.) 

pipe  [message-list]  [shell-command] 

I  [message-list]  [shell-command] 

Pipe  the  message  through  shell-command.  The  message  is  treated  marked  as  read 
(and  normally  saved  to  the  mbox  file  when  mail  exits).  If  no  arguments  are  given, 
the  current  message  is  piped  through  the  command  specified  by  the  value  of  the  cmd 
variable.  If  the  page  variable  is  set,  a  form  feed  character  is  inserted  after  each  mes¬ 
sage. 

preserve  [message-list] 

Same  as  the  hold  command. 
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print  [message-list] 

type  [message-list]  Print  the  specified  messages.  If  the  crt  variable  is  set,  messages  longer  than  the 
number  of  lines  it  indicates  paged  through  the  command  specified  by  the  PAGER 
variable.  The  default  paging  command  is  niore(l). 

Print  [message-list] 

Type  [message-list]  Print  the  specified  messages  on  the  screen,  including  all  header  fields.  Overrides 
suppression  of  fields  by  the  ignore  and  retain  commands. 

quit  Exit  from  mail  storing  messages  that  were  read  in  the  mbox  file  and  unread  messages 

in  the  system  mailbox.  Messages  that  have  been  explicitly  saved  in  a  file  are  deleted 
unless  the  variable  keepsave  is  set. 

reply  [message-list] 
respond  [message-list] 
replysender  [message-list] 

Send  a  response  to  the  author  of  each  message  in  the  message-list.  The  subject  line 
is  taken  from  the  first  message.  If  record  is  set  to  a  filename,  a  copy  of  the  reply  is 
added  to  that  file.  If  the  replyall  variable  is  set,  the  actions  of  Reply/Respond  and 
reply/respond  are  reversed.  The  replysender  command  is  not  affected  by  the 
replyall  variable,  but  sends  each  reply  only  to  the  sender  of  each  message. 


Reply  to  the  specified  message,  including  all  other  recipients  of  that  message.  If  the 
variable  record  is  set  to  a  filename,  a  copy  of  the  reply  added  to  that  file.  If  the 
replyall  variable  is  set,  the  actions  of  Reply/Respond  and  reply/respond  are 
reversed.  The  replyall  command  is  not  affected  by  the  replyall  variable,  but  always 
sends  the  reply  to  all  recipients  of  the  message. 

Add  the  list  of  header  fields  named  to  the  retained  list.  Only  the  header  fields  in  the 
retain  list  are  shown  on  your  terminal  when  you  print  a  message.  All  other  header 
fields  are  suppressed.  The  set  of  retained  fields  specified  by  the  retain  command 
overrides  any  list  of  ignored  fields  specified  by  the  ignore  command.  The  Type  and 
Print  commands  can  be  used  to  print  a  message  in  its  entirety.  If  retain  is  executed 
with  no  arguments,  it  lists  the  current  set  of  retained  fields. 

save  [message-list]  [filename] 

Save  the  specified  messages  in  the  named  file.  The  file  is  created  if  it  does  not  exist. 
If  no  filename  is  specified,  the  file  named  in  the  MBOX  variable  is  used,  mbox  in 
your  home  directory  by  default.  Each  saved  message  is  deleted  from  the  system 
mailbox  when  mail  terminates  unless  the  keepsave  variable  is  set.  See  also  the  exit 
and  quit  commands. 

Save  [message-list]  Save  the  specified  messages  in  a  file  whose  name  is  derived  from  the  author  of  the 
first  message.  The  name  of  the  file  is  taken  from  the  author’s  name,  with  all  network 
addressing  stripped  off.  See  also  the  Copy,  followup,  and  Followup  commands  and 
the  outfolder  variables. 

set  [variable  [=value]  ] 

Define  a  variable.  To  assign  a  value  to  variable,  separate  the  variable  name  from 
the  value  by  an  *=’  (there  must  be  no  space  before  or  after  the  ‘=’).  A  variable  may 
be  given  a  null,  string,  or  numeric  value.  To  embed  SPACE  characters  within  a  value 
enclose  it  in  quotes. 

With  no  arguments,  set  displays  all  defined  variables  and  any  values  they  might 
have.  See  Variables  for  a  description  of  all  predefined  mail  variables. 

shell  Invoke  the  interactive  shell  listed  in  the  SHELL  variable. 
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size  [message-list]  Print  the  size  in  characters  of  the  specified  messages. 

source  filename  Read  commands  from  the  given  file  and  return  to  command  mode. 

top  [message-list]  Print  the  top  few  lines  of  the  specified  messages.  If  the  toplines  variable  is  set,  it  is 

taken  as  the  number  of  lines  to  print.  The  default  number  is  5. 

touch  [message-list]  Touch  the  specified  messages.  If  any  message  in  message-list  is  not  specifically 
saved  in  a  file,  it  will  be  placed  in  the  mbox  upon  normal  termination.  See  also  the 
exit  and  quit  commands. 

type  [message-list]  Same  as  the  print  command. 

Type  [message-list]  Same  as  the  Print  command, 
undelete  [message-list] 

Restore  deleted  messages.  This  command  only  restores  messages  deleted  in  the 
current  mail  session.  If  the  autoprint  variable  is  set,  the  last  message  restored  is 
printed. 

unread  [message-list] 

Unread  [message-list] 

Same  as  the  new  command. 

unset  variable  . . .  Erase  the  specified  variables.  If  the  variable  was  imported  from  the  environment 
(that  is,  an  environment  variable  or  exported  shell  variable),  it  cannot  be  unset  from 
within  mail. 

version  Print  the  current  version  and  release  date  of  the  mail  utility, 

visual  [message-list]  Edit  the  given  messages  with  the  screen  editor  listed  in  the  VISUAL  variable.  The 
default  screen  editor  is  vi(l).  Each  message  is  placed  in  a  temporary  file  for  editing. 

write  [message-list]  [filename] 

Write  the  given  messages  onto  the  specified  file,  but  without  the  header  and  trailing 
blank  line.  Otherwise,  this  is  equivalent  to  the  save  command. 

xit  Same  as  the  exit  command. 

z[  +  l-]  Scroll  the  header  display  forward  (+)  or  backward  (-)  one  screenfull.  The  number 

of  headers  displayed  is  set  by  the  screen  variable. 

Forwarding  Messages 

To  forward  a  specific  message,  include  it  in  a  message  to  the  desired  recipients  with  the  ~f  or  ~m  tilde 
escapes.  To  forward  mail  automatically,  add  a  comma-separated  list  of  addresses  for  additional  recipients 
to  the  .forward  file  in  your  home  directory.  This  is  different  from  the  format  of  the  alias  command,  which 
takes  a  space-separated  list  instead.  Note:  forwarding  addresses  must  be  valid  (as  described  in  aliases(5)), 
or  the  messages  will  “bounce.”  You  cannot,  for  instance,  reroute  your  mail  to  a  new  host  by  forwarding  it 
to  your  new  address  if  it  is  not  yet  listed  in  the  NIS  aliases  domain. 

Variables 

The  behavior  of  mail  is  governed  by  a  set  of  predefined  variables  that  are  set  and  cleared  using  the  set  and 
unset  commands. 

Environment  Variables 

Values  for  the  following  variables  are  read  in  automatically  from  the  environment;  they  cannot  be  altered 
from  within  mail: 

UOME:=directory 

The  user’s  home  directory. 

MAlL=filename 

The  name  of  the  initial  mailbox  file  to  read  (in  lieu  of  the  standard  system  mailbox).  The 
default  is  lysffl&pooVmsdMusername . 


Sun  Release  4.1 


Last  change:  19  December  1988 


313 


MAIL(l) 


USER  COMMANDS 


MAIL(l) 


MAILRC=/z/emime 

The  name  of  the  personal  stan-up  file.  The  default  is  $HOME/.mailrc. 

Mail  Variables 

The  following  variables  can  be  initialized  within  the  .mailrc  file,  or  set  and  altered  interactively  using  the 
set  command.  They  can  also  be  imported  from  the  environment  (in  which  case  their  values  cannot  be 
changed  within  mail).  The  unset  command  clears  variables.  The  set  command  can  also  be  used  to  clear  a 
variable  by  prefixing  the  word  no  to  the  name  of  the  variable  to  clear. 

Variables  for  which  values  are  normally  supplied  are  indicated  with  an  equal-sign  (=).  The  equal-sign  is 
required  by  the  set  command,  and  there  can  be  no  spaces  between  the  variable-name,  equal-sign,  and  value, 
using  set  to  assign  a  value. 

allnet  All  network  names  whose  last  component  (login  name)  match  are  treated  as  identical. 

This  causes  the  message  list  specifications  to  behave  similarly.  Default  is  noallnet.  See 
also  the  alternates  command  and  the  metoo  variable. 

alwaysignore  Ignore  header  fields  with  ignore  everywhere,  not  just  during  print  or  type.  Affects  the 
save.  Save,  copy.  Copy,  top,  pipe,  and  write  commands,  and  the  ~m  and  ~f  tilde  escapes. 

append  Upon  termination,  append  messages  to  the  end  of  the  mbox  file  instead  of  prepending 

them.  Default  is  noappend  but  append  is  set  in  the  global  start-up  file  (which  can  be 
suppressed  with  the  -n  command  line  option). 

askee  Prompt  for  the  Cc  list  after  message  is  entered.  Default  is  noaskcc. 

asksub  Prompt  for  subject  if  it  is  not  specified  on  the  command  line  with  the  -s  option.  Enabled 

by  default. 

autoprint  Enable  automatic  printing  of  messages  after  delete  and  undelete  commands.  Default  is 

noautoprint. 

bang  Enable  the  special-casing  of  exclamation  points  (!)  in  shell  escape  command  lines  as  in 

vi(l).  Default  is  nobang. 

cnid=shell-command 

Set  the  default  command  for  the  pipe  command.  No  default  value. 

conv=conversion 

Convert  uucp  addresses  to  the  address  style  specified  by  conversion ,  which  can  be  either: 

internet 

This  requires  a  mail  delivery  program  conforming  to  the  RFC822  standard  for 
electronic  mail  addressing. 

optimize 

Remove  loops  in  uucp(lC)  address  paths  (typically  generated  by  the  reply  com¬ 
mand).  No  rerouting  is  performed;  mail  has  no  knowledge  of  UUCP  routes  or 
connections. 

Conversion  is  disabled  by  default.  See  also  sendmail(8)  and  the  -U  command  line 
option. 

cri=number  Pipe  messages  having  more  than  number  lines  through  the  command  specified  by  the 
value  of  the  PAGER  variable  {more  by  default).  Disabled  by  default. 

DEAD=filename 

The  name  of  the  file  in  which  to  save  partial  letters  in  case  of  untimely  interrupt  or 
delivery  errors.  Default  is  the  file  dead.letter  in  your  home  directory. 

debug  Enable  verbose  diagnostics  for  debugging.  Messages  are  not  delivered.  Default  is  node¬ 

bug. 
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dot  Take  a  period  on  a  line  by  itself  during  input  from  a  terminal  as  EOF.  Default  is  nodot  but 

dot  is  set  in  the  global  start-up  file  (which  can  be  suppressed  with  the  -n  command  line 
option). 

editheaders  Include  message  headers  in  the  text  to  be  edited  by  the  "e  and  “v  commands. 

EDIT  OR^hell-command 

The  command  to  run  when  the  edit  or  ~e  command  is  used.  Default  is  ex(l). 
escape=c  Substitute  c  for  the  -  escape  character. 

fo\deT=directory 

The  directory  for  saving  standard  mail  files.  User  specified  file  names  beginning  with  a 
plus  (+)  are  expanded  by  preceding  the  filename  with  this  directory  name  to  obtain  the 
real  filename.  If  directory  does  not  start  with  a  slash  (/),  the  value  of  HOME  is  prepended 
to  it.  There  is  no  default  for  the  folder  variable.  See  also  outfolder  below. 

Enable  printing  of  the  header  summary  when  entering  mail.  Enabled  by  default. 

Preserve  all  messages  that  are  read  in  the  system  mailbox  instead  of  putting  them  in  the 
standard  mbox  save  file.  Default  is  nohold  for  mail  and  hold  for  mailtool(l). 

Ignore  interrupts  while  entering  messages.  Handy  for  noisy  dial-up  lines.  Default  is 
noignore. 

Ignore  EOF  during  message  input.  Input  must  be  terminated  by  a  period  on  a  line  by 
itself  or  by  the  command.  Default  is  noignoreeof.  See  also  dot  above. 

indentprefix=jfri>ig 

When  indentprefix  is  set,  string  is  used  to  mark  indented  lines  from  messages  included 
with  ~m.  The  default  is  a  TAB  character. 

keep  When  the  system  mailbox  is  empty,  truncate  it  to  zero  length  instead  of  removing  it.  Dis¬ 

abled  by  default. 

keepsave  Keep  messages  that  have  been  saved  in  other  files  in  the  system  mailbox  instead  of  delet¬ 
ing  them.  Default  is  nokeepsave. 

LlSl!ER=sheU-command 

The  command  (and  options)  to  use  when  listing  the  files  in  the  folder  directory.  The 
default  is  Is(lV). 

MBOX=filename 

The  name  of  the  file  to  save  messages  which  have  been  read.  The  xit  command  overrides 
this  variable,  as  does  saving  the  message  explicitly  to  another  file.  Default  is  the  file 
mbox  in  your  home  directory. 

If  your  login  appears  as  a  recipient,  do  not  delete  it  from  the  list.  Default  is  nometoo. 
When  used  as  a  prefix  to  a  variable  name,  has  the  effect  of  unsetting  the  variable. 

When  responding  to  a  message  that  was  originally  sent  to  several  recipients,  the  other 
recipient  addresses  are  normally  forced  to  be  relative  to  the  originating  author’s  machine 
for  the  response.  This  flag  disables  alteration  of  the  recipients’  addresses,  improving 
efficiency  in  a  network  where  all  machines  can  send  directly  to  all  other  machines  (that  is, 
one  “hop”  away). 

Locate  the  files  used  to  record  outgoing  messages  in  the  directory  specified  by  the  folder 
variable  unless  the  pathname  is  absolute.  Default  is  nooutfolder.  See  folder  above  and 
the  Save,  Copy,  followup,  and  Followup  commands. 

Used  with  the  pipe  command  to  insert  a  form  feed  after  each  message  sent  through  the 
pipe.  Default  is  nopage. 
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V  PiGEi'Rtsshell-cmtmand 

The  command  to  use  as  a  filter  for  paginating  output,  along  with  any  options  to  be  used. 
Default  is  more(l). 

prompt= Jtrirtg  Set  the  command  mode  prompt  to  string .  Default  is  ‘ . 

Refrain  from  printing  the  opening  message  and  version  when  entering  mail.  Default  is 
noquiet. 

record=^/ename 

Record  all  outgoing  mail  in  filename.  Disabled  by  default.  See  also  the  variable  out- 
folder. 

replyall  Reverse  the  effect  of  the  reply  and  Reply  commands. 

save  Enable  saving  of  messages  in  the  dead.letter  file  on  interrupt  or  delivery  error.  See  DEAD 

for  a  description  of  this  file.  Enabled  by  default. 

screen=«M/Mbgr  Set  the  number  of  lines  in  a  screen-full  of  headers  for  the  headers  command. 

s^i\Am?A\=shell-command 

Alternate  command  for  delivering  messages.  Note:  in  addition  to  the  expected  list  of 
recipients,  mail  also  passes  the  -i  and  ~m,  flags  to  the  command.  Since  these  flags  are 
not  appropriate  to  other  commands,  you  may  have  to  use  a  shell  script  that  strips  them 
from  the  arguments  list  before  invoking  the  desired  command. 

sendwait  Wait  for  background  mailer  to  finish  before  returning.  Default  is  nosendwait. 

SH^\A^=shell-command 

The  name  of  a  preferred  command  interpreter.  Typically  inherited  from  the  environment, 
the  shell  is  normally  the  one  you  always  use.  Otherwise  defaults  to  sh(l). 

showto  When  displaying  the  header  summary  and  the  message  is  from  you,  print  the  recipient’s 

name  instead  of  the  author’s  name. 

s\gn=autograph  The  autograph  text  inserted  into  the  message  when  the  -a  (autograph)  command  is  given. 
No  default  (see  also  the  -i  tilde  escape). 

S\gn=autograph  The  autograph  text  inserted  into  the  message  when  the  ~A  command  is  given.  No  default 
(see  also  the  ~i  tilde  escape). 

toii\mes=number 

The  number  of  lines  of  header  to  print  with  the  top  command.  Default  is  5. 
verbose  Invoke  sendmail  with  the  -v  flag. 

yiSU  A'L=shell-comjnand 

The  name  of  a  preferred  screen  editor.  Default  is  vi. 


FILES 

$HOMK/ ,mailrc 

%llOMELforward 

$llOME/mbox 

$HOME/dead.letter 

/var/spool/mail 

/usr/lib/Mail.he]p’*‘ 

/usr/Iib/MaiLrc 

/tmp/R[emqsx]* 


personal  start-up  file 

list  of  recipients  for  automatic  forwarding  of  messages 

secondary  storage  file 

undeliverable  messages  file 

directory  for  system  mailboxes 

help  message  files 

global  start-up  file 

temporary  files 
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SEE  ALSO 

biff(l),  bin-inail(l),  echo(lV),  ex(l),  fint(l),  Is(lV),  inailtool(l),  more(l),  sh(l),  uucp(lC),  vacation(l), 
vi(l),  aliases(5),  newaliases(8),  sendinail(8) 

SunOS  User's  Guide:  Getting  Started 

mail  is  found  in  /usr/ucb/Mail,  as  a  link  to  /usr/ucb/mail.  If  you  wish  to  use  the  original  (version  7)  UNIX 
mail  program,  you  can  find  it  in  /usr/bin/mail.  Its  man  page  is  named  bin-mail(l). 

BUGS 

Where  shell-command  is  shown  as  valid,  arguments  are  not  always  allowed.  Experimentation  is  recom¬ 
mended. 

Internal  variables  imported  firom  the  execution  environment  cannot  be  unset. 

Replies  do  not  always  generate  correct  return  addresses.  Try  resending  the  errant  reply  with  onehop  set. 

mail  does  not  lock  your  record  file.  So,  if  you  use  a  record  file  and  send  two  or  more  messages  simultane¬ 
ously,  lines  from  the  messages  may  be  interleaved  in  the  record  file. 

The  format  for  the  alias  command  is  a  space-separated  list  of  recipients,  while  the  format  for  an  alias  in 
either  the  .forward  or  /etc/aliases  is  a  comma-separated  list. 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed. 
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NAME 

mailtool  -  SunView  interface  for  the  mail  program 
SYNOPSIS 

mailtool  [  ~Mx  ]  [  —Mi  interval  ]  [  generic-tool-arguments  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

mailtool  is  the  standard  SunView  interface  to  mail(l).  It  provides  a  window  and  mouse-based  interface 
for  reading,  storing,  composing,  and  sending  mail  messages.  Scrollable  windows  allow  easy  access  to  your 
mailbox  and  mail  folders.  Software  “panel  buttons”  make  frequently-used  commands  readily  available. 
Less-used  commands  are  accessible  from  menus,  and  keyboard  accelerators  are  provided  for  the  more 
experienced  user. 

The  full  editing  capabilities  of  textedit(l)  and  the  SunView  selection  service  are  available  for  modifying 
and  composing  mail.  In  addition,  you  can  customize  mailtool  by  setting  various  parameters  with 
defaultsedit(l). 

OPTIONS 

“Mx  Expert  mode.  Do  not  ask  for  confirmation  after  potentially  damaging  mail  commands. 

This  has  the  same  effect  as  setting  the  expert  variable. 

-Mi  interval  Check  for  new  mail  every  interval  seconds.  This  has  the  same  effect  as  specifying  a 
value  for  the  interval  variable. 


generic-tool-arguments 

mailtool  accepts  the  generic  tool  arguments  described  in  sunview(l). 


USAGE 

Users  who  are  not  familiar  with  the  mail  command  should  read  SunOS  User’s  Guide:  Getting  Started .  For 
more  information  on  text  editing  and  the  selection  service,  see  the  SunView  User’s  Guide. 


mailtool  comes  up  closed.  You  can  open  the  tool  by  clicking  on  the  icon  with  the  LEFT  mouse  button, 
mailtool  starts  reading  your  system  mailbox  as  it  opens.  Alternatively,  the  frame  menu  on  the  icon  con¬ 
tains  the  Open  pull-right  item,  which  allows  you  to  open  mailtool  to  a  selected  folder,  or  open  and  Com¬ 
pose,  or  just  open  without  performing  any  other  operation. 


Subwindows 

mailtool  is  composed  of  six  parts.  From  top  to  bottom,  they  are: 
frame  header 

This  is  the  broad  stripe  at  the  top  of  the  tool,  and  it  displays  status  information.  The  right 
side  displays  information  about  the  most-recently  executed  command.  The  left  side  displays 
other  information  such  as  the  name  of  the  current  folder.  When  involved  in  a  lengthy  opera¬ 
tion,  mailtool  displays  a  message  to  that  effect  on  the  left  side.  While  an  operation  is  pend¬ 
ing,  the  cursor  takes  on  the  shape  of  an  hourglass;  you  must  wait  until  it  finishes. 

header-list  window 

This  read-only  text  window  contains  a  list  of  message  headers  from  the  current  folder  or 
mailbox.  Initially,  it  shows  the  contents  of  your  system  mailbox  (by  default).  Each  header 
typically  contains  fields  indicating  who  the  message  is  from,  its  subject,  and  so  forth.  There 
is  a  scrollbar  to  the  left  that  you  can  use  to  scroll  through  the  headers. 
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control  panel 

This  panel  contains  a  collection  of  software  buttons  corresponding  to  the  most  frequently 
used  mail(l)  commands.  Clicking  on  one  of  these  buttons  starts  the  indicated  operation  for 
either  the  selected  or  the  current  message.  Commands  that  require  the  name  of  a  folder, 
such  as  Save,  use  the  contents  of  the  ‘Filer’  text  item.  You  must  enter  the  name  of  a  file  or 
folder  in  this  space  before  clicking  on  the  button. 

In  addition  to  the  panel  buttons,  other  commands  and  variations  are  accessible  through 
menus  “behind”  each  panel  button.  To  display  a  button  menu,  hold  down  the  RIGHT  mouse 
button  over  the  panel  button.  See  Command  Menus,  below,  for  details. 

The  message  window 

This  text  window  displays  the  current  message  (marked  with  ‘>’  in  the  header  window). 
You  can  edit  this  message,  in  which  case  the  result  replaces  the  original  message  in  the 
mailbox  or  folder. 

composition  panel 

This  panel  contains  software  buttons  for  composing  or  replying  to  messages,  and  is  visible 
only  when  you  are  composing  a  message  or  reply. 

composition  window 

This  text  window,  in  which  you  compose  messages  to  send,  appears  in  conjunction  with  the 
composition  panel.  It  is  normally  displayed  only  when  composing  a  message  or  reply.  It  is 
initially  loaded  with  mail  header  lines  such  as  ‘To:’  and  ‘Subject:’,  and  perhaps,  ‘Cc:’. 
After  these  labels  come  various  text  fields,  such  as  |>recipients<|.  You  can  move  from  field 
to  field  using  CTRL-TAB,  This  advances  to  the  next  text  field.  If  you  supply  input  to  the 
field,  your  input  replaces  its  contents.  Empty  fields  are  deleted  when  the  message  is  sent. 
You  can  continue  to  edit  the  message  as  you  see  fit  until  you  click  on  Deliver,  at  which 
point  the  message  is  sent  as  is.  (You  normally  cannot  retrieve  a  message  once  it  has  been 
sent). 

pop-up  composition  window 

While  composing  a  message  or  reply,  clicking  again  on  Compose  or  Reply,  opens  another 
frame  that  contains  a  composition  panel  and  window.  The  only  limit  on  the  number  of  such 
pop-up  composition  frames  is  the  number  of  windows  that  a  tool  can  support.  These  addi¬ 
tional  frames  operate  independently. 

Basic  Mailtool  Concepts 
Choosing  a  message 

To  choose  a  message,  place  the  cursor  anywhere  in  its  header  in  the  header  window  and 
click  the  LEFT  mouse  button.  If  there  is  no  message  chosen,  mailtool  applies  operations  to 
the  current  message. 

Current  message 

The  message  that  is  displayed  in  the  message  window,  and  flagged  w|th  a  ‘>’  in  the  header 
window. 

Confirmation 

Some  operations  require  confirmation,  in  which  case  an  alert  is  displayed.  You  can  then 
confirm  or  cancel  the  operation. 

Folders 

When  mailtool  starts  up,  it  normally  reads  your  system  mailbox.  However,  you  can  select 
another  “folder”  (file  containing  mail  messages)  from  which  to  read. 

Committing  Changes 

Some  operations  change  the  state  of  your  system  mailbox  or  the  current  folder.  These 
changes  are  not  finalized  until  you  commit  them.  For  instance,  you  can  “undelete”  mes¬ 
sages  that  were  deleted,  provided  that  you  have  not  yet  done  an  operation  that  commits  your 
changes.  If  the  mailtool  session  is  interrupted,  pending  changes  to  the  mailbox  or  folder  do 
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not  take  effect.  The  Done  button  commits  changes,  as  does  the  Quit  button,  which  also 
exits  from  mailtool.  To  deliberately  exit  without  committing,  use  the  pop-up  menu  behind 
the  Quit  button. 

Control  Panel 

Except  for  the  Next  and  Undelete  buttons,  mailtool  commands  operate  on  the  selected  message  or  the 
current  message  only.  You  cannot  specify  a  list  or  range  of  messages  as  with  mail(l).  The  control  panel 
buttons  and  items  are  (in  alphabetical  order): 

Open  a  composition  panel  and  window  to  compose  a  message. 

Delete  the  selected  or  current  message. 

Commit  changes,  close  mailtool,  and  read  new  mail  on  next  Open. 

This  is  a  text  item  in  which  to  enter  the  name  of  a  folder  for  the  Save,  Copy,  and  Folder 
commands.  This  name  can  be  a  full  pathname,  a  pathname  relative  to  the  current  directory 
(the  directory  mailtool  was  started  from),  or  a  filename  prefixed  with  a  *+’  to  refer  to  a  file 
in  the  “folder”  directory. 

Commit  changes  and  switch  to  the  file  or  folder  specified  in  the  ‘File:’  text  item. 

Display  a  pop-up  panel  to  change  the  current  directory  of  mailtool.  Other  miscellaneous 
operations  are  available  on  the  menu  behind  this  button. 

If  you  are  examining  your  system  mailbox,  retrieve  new  mail  without  committing  changes. 
If  your  are  examining  a  folder,  commit  any  changes  to  the  folder,  switch  back  to  system 
mailbox,  and  retrieve  any  new  mail  in  the  process. 

Display  the  message  following  the  current  message  in  the  message  window. 

Print  the  corresponding  message  on  a  hardcopy  printer. 

Open  a  composition  window  to  reply  to  the  selected  or  current  message. 

Save  the  current  or  selected  message  in  the  folder  specified  in  the  ‘File:’  text  field,  and 
delete  it  from  your  system  mailbox  or  current  folder. 

Display  the  chosen  or  current  message  in  the  message  window. 

The  Composition  Panel 

This  panel  contains  four  buttons  and  a  cycle-item.  The  cycle-item  controls  the  behavior  of  the  composition 
window  when  it  becomes  inactive  —  when  the  user  delivers  or  cancels  a  message.  Items  in  the  cycle  are: 

Disappear  Remove  the  composition  window  and  panel  from  display.  This  is  the  default. 

Stay  Up  Clear  the  window,  but  leave  it  displayed. 

Close  Close  a  pop-up  composition  frame. 

The  panel  buttons  are: 

Cancel  Abort  the  message  being  composed. 

Deliver  Send  the  message  being  composed  to  the  indicated  recipients. 

Include  Insert  the  corresponding  message  into  the  composition  window  at  the  caret.  This  operation 
can  be  performed  repeatedly,  to  include  various  messages. 

Re-address  Insert  the  appropriate  ‘To:’,  ‘Subject:’  and  ‘Cc:’  fields  at  the  top  of  the  composition  win¬ 
dow. 

Command  Menus 

All  panel  buttons  have  menus  behind  them.  The  first  item  on  the  menu  is  the  default  command;  choosing 
this  item  is  the  same  as  clicking  on  the  panel  button. 


Compose 

Delete 

Done 

File: 


Folder 

Misc 

New  Mail 

Next 

Print 

Reply 

Save 

Show 


\ 


320 


Last  change:  2  October  1989 


Sun  Release  4.1 


MAILTOOL(l) 


USER  COMMANDS 


MAILTOOL(l) 


Some  menu  items  are  pull-right  to  menus  of  related  commands.  You  can  browse  the  button  menus  to  dis¬ 
cover  what  additional  commands  are  available,  and  what  their  accelerators  are,  if  any.  The  following  com¬ 
mands  are  particularly  useful. 

Change  Directory 

Display  a  pop-up  panel  to  change  the  current  directory. 

Commit  Changes 

Commit  changes.  This  item  is  behind  the  New  Mail  button  when  viewing  a  folder. 
Commit  Changes  and  Quit 

Behind  the  Done  button.  Commit  changes  and  exit  mailtool(l).  This  is  the  same  as 
choosing  Quit  from  the  frame  menu. 

Commit  Changes  and  Retrieve  New  Mail 

Behind  the  New  Mail  button.  Commit  changes  and  retrieve  new  mail,  switching  to  the 
system  mail  box  if  in  a  folder.  This  is  the  default  when  viewing  a  folder. 

Copy  Behind  the  Save  button.  Copy  the  selected  message  to  the  file  or  folder  specified  in  the 

‘File:’  text  item,  without  deleting  it  from  the  mailbox  or  folder. 

Deliver,  Leave  Window  Intact 

Behind  the  Deliver  button.  Deliver  the  message,  but  do  not  undisplay,  close,  or  clear  the 
message  composition  window. 

Include,  Indented 

Behind  the  Include  button.  Include  the  indicated  message,  setting  it  off  by  indentation 
rather  than  bracketing  it  with  Begin  Included  Message  — ’  and  ‘ —  End  Included 
Message  —  ’  lines. 

Previous  Behind  the  Next  button.  Display  the  previous  message  in  the  message  window. 

Quit  without  Committing  Changes 

Behind  the  Done  button.  Exit  mailtool  without  committing  changes. 

Show  Full  Header 

Behind  the  Show  button.  Display  the  complete  message  in  the  message  window,  includ¬ 
ing  header  lines  that  are  normally  ignored. 

Source  .mailrc  Behind  the  Misc  button.  Read  in  your  .mailrc  file  to  acquire  new  variables  and  settings. 

Note:  this  operation  does  not  “forget”  the  previous  option  settings;  only  changes  to 
boolean  variables  take  effect. 

Undelete  Behind  the  Delete  button.  Undelete  the  most  recendy  deleted  message(s)  —  this  may  be 

used  repeatedly.  It  is  inactive  when  there  are  no  deleted  messages. 

There  are  two  special  menus  for  use  with  the  ‘File:’  text  item.  Choosing  a  name  from  either  of  these 
menus  replaces  the  contents  of  this  item.  The  menu  behind  the  ‘File:’  item  holds  the  most  recently  used 
folder  names  of  the  current  session.  It  is  be  initialized  by  the  filemenu  variable.  The  menu  behind  the 
Folder  button  displays  all  folders  in  the  “folder”  directory,  which  is  specified  by  the  folder  variable 
(described  in  mall(l)).  Folders  can  be  organized  into  subdirectories  within  the  folder  directory.  Files  in 
these  subdirectories  appear  in  a  hierarchy  of  pull-right  menus. 

To  switch  to  a  folder,  choose  it  from  one  of  the  file  menus,  or  type  it  in  directly,  and  click  on  the  Folder 
button.  To  return  to  your  system  mailbox,  use  the  New  Mail  button. 

Mailtool  Variables 

In  addition  to  the  variables  recognized  by  mail(l),  mailtool  recognizes  those  listed  below.  They  can  be  set 
by  using  defaultsedit(l),  or  by  editing  your  .mailrc  file  directly.  Unless  otherwise  noted,  the  default  for 
the  following  variables  is  off. 
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allowreversescan 

When  set,  allows  you  to  step  through  messages  in  latest-first  oldest-first  order  if  you 
choose.  The  next  message  depends  on  the  order  of  travel. 

alwaysusepopup  Never  split  the  message  window  to  compose  or  reply;  always  use  pop-up  composition 
windows. 

askbcc  Prompt  for  the  ‘Bcc:*  field  when  composing  or  replying. 

autoprint  Display  the  next  message  when  the  current  message  is  deleted  or  saved. 

bell  The  number  of  times  to  ring  the  bell  when  new  mail  arrives.  The  default  is  0. 

disablefields  Do  not  use  text  fields  in  the  composition  window.  The  default  is  to  use  text  fields. 

editmessagewindow 

Request  confirmation  before  the  first  editing  operation  to  a  message  in  the  message  win¬ 
dow  (as  opposed  to  composing  a  reply).  The  default  is  not  to  request  confirmation  of  the 
first  edit. 


expert  Set  expert  mode  in  which  no  confirmations  are  requested. 

filemenu  A  list  of  files  from  which  to  initialize  the  ‘File:’  menu.  These  can  be  absolute  path¬ 

names,  pathnames  relative  to  the  working  directory  for  mailtool  (typically  your  home 
directory),  or  filenames  prefixed  with  a  ‘+’,  which  are  taken  as  relative  to  the  directory 
specified  in  the  folder  variable  (see  mail(l)). 

filemenusize  Specifies  the  maximum  size  of  the  ‘File:’  menu.  The  default  is  10. 

fl^sh  The  number  of  times  to  flash  the  window  or  icon  when  new  mail  arrives.  The  default  is 

0. 


headerlines 

interval 

maillines 

moveinputfocus 

pop-uplines 

msgpercent 

printmail 

trash 


The  number  of  lines  in  header  window.  The  default  is  10. 

The  interval  in  seconds  to  check  for  new  mail.  The  default  is  300. 

The  number  of  lines  in  mail  message  window.  The  default  is  30. 

Move  the  input  focus  into  the  composition  window  for  Compose  and  Reply.  This  only 
works  for  click-to-type. 

The  number  of  lines  in  pop-up  message  composition  window.  The  default  is  30. 

The  percent  of  the  message  window  to  remain  visible  during  Compose  or  Reply.  The 
default  is  50. 

The  command  to  use  to  print  a  message.  The  default  is  ‘Ipr  -p’. 

The  name  of  trash  bin,  which  may  be  accessed  just  like  any  other  folder.  If  set,  all 
deleted  messages  are  moved  to  the  trash  bin.  The  trash  bin  is  emptied  when  you  commit 
changes. 


Conditional  Settings 

You  can  make  your  .mailrc  set  variables  conditionally,  depending  on  whether  it  is  running  in  the  tty 
environment  or  the  window  environment.  See  SunOS  User's  Guide:  Getting  Started  for  details. 


ENVIRONMENT 

The  environment  variables  LC__CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  mailtool.  On  entry  to  mailtool,  these  environment  variables  are  checked  in  the  following 
order:  LC_CTYPE,  LANG,  and  LC_derault.  When  a  valid  value  is  found,  remaining  environment  vari¬ 
ables  for  character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the 
current  valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  char¬ 
acter  classification  defaults  to  the  POSDC.l  “C”  locale. 
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FILES 

/var/spool/mail/*  system  mailboxes 

7.mailrc  startup  file  for  mail  and  mailtool 

SEE  ALSO 

biii-mail(l),  defaultsedit(l),  mail(l),  sunvi€w(l),  textedit(l)  aliases(5),  locaIe(5),  newaliases(8).  send- 
mail(8) 

SunOS  User's  Guide:  Getting  Started 
SunView  User's  Guide 

BUGS 

If  mail(l)  receives  an  error,  then  mailtool  may  hang,  in  which  case  you  must  kill  it. 

New  mail  status  is  only  approximate,  therefore  the  presence  of  new  mail  is  not  always  accurately  reflected 
in  the  icon  image  or  tool  frame  header. 

Mouse  input  may  be  lost  while  mailtool  switches  to  iconic  state. 

When  notifying  you  of  new  mail,  mailtool  will  not  flash  the  window  or  icon  without  beeping  (ringing  the 
audible  bell).  Thus,  the  number  of  flashes  is  limited  by  the  number  of  beeps  you  set. 

Unlike  mail(l),  mailtool  retains  unsaved  messages  in  the  system  mailbox  by  default;  that  is,  the  hold  vari¬ 
able  is  initially  set. 
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NAME 

make  -  maintain,  update,  and  regenerate  related  programs  and  files 
SYNOPSIS 

[-d]  [-dd]  [-D]  [-DD]  [-e]  [-i]  [-k]  [-n]  [-p]  [-P]  [-q]  [-r] 

[  -s  ]  [  ~S  ]  [  -t  ]  [  target . . .  ]  [  macro=value  . . .  ] 

DESCRIPTION 

make  executes  a  list  of  shell  commands  associated  with  each  target,  typically  to  create  or  update  a  file  of 
the  same  name,  makefile  contains  entries  that  describe  how  to  bring  a  target  up  to  date  with  respect  to 
those  on  which  it  depends,  which  are  called  dependencies.  Since  each  dependency  is  a  target,  it  may  have 
dependencies  of  its  own.  Targets,  dependencies,  and  sub-dependencies  comprise  a  tree  structure  that  make 
traces  when  deciding  whether  or  not  to  rebuild  a  target, 

make  recursively  checks  each  target  against  its  dependencies,  beginning  with  the  first  target  entry  in 
makefile  if  no  target  argument  is  supplied  on  the  command  line.  If,  after  processing  all  of  its  dependencies, 
a  target  file  is  found  either  to  be  missing,  or  to  be  older  than  any  of  its  dependencies,  make  rebuilds  it! 
Optionally  with  this  version  of  make,  a  target  can  be  treated  as  out-of-date  when  the  commands  used  to 
generate  it  have  changed  since  the  last  time  the  target  was  built. 

To  build  a  given  target,  make  executes  the  list  of  commands,  called  a  rule.  This  rule  may  be  listed  expli¬ 
citly  in  the  target’s  makefile  entry,  or  it  may  be  supplied  implicitly  by  make. 

When  no  makefile  is  specified  with  a  -f  option: 

•  If  there  is  a  file  named  makefile  in  the  working  directory,  make  uses  that  file.  If,  however, 
there  is  an  SCCS  history  file  (SCCS/s.makefi]e)  which  is  newer,  make  attempts  to  retrieve  and 
use  the  most  recent  version. 

•  In  the  absence  of  the  above  file(s),  if  a  file  named  Makefile  is  present  in  the  working  directory, 
make  attempts  to  use  it.  If  there  is  an  SCCS  history  file  (SCCS/s.Makefile)  that  is  newer, 
make  attempts  to  retrieve  and  use  the  most  recent  version. 

If  no  target  is  specified  on  the  command  line,  make  uses  the  first  target  defined  in  makefile. 

If  a  target  has  no  makefile  entry,  or  if  its  entry  has  no  rule,  make  attempts  to  derive  a  rule  by  each  of  the 
following  methods,  in  turn,  until  a  suitable  rule  is  found.  (Each  method  is  described  under  USAGE  below.) 

•  Pattern  matching  rules. 

•  Implicit  rules,  read  in  from  a  user-supplied  makefile. 

•  Standard  implicit  rules  (also  known  as  suffix  rules),  typically  read  in  from  the  file 
<make/default.mk>. 

•  SCCS  retrieval,  make  retrieves  the  most  recent  version  from  the  SCCS  history  file  (if  any). 
See  the  description  of  the  .SCCS_GET:  special-function  target  for  details. 

•  The  rule  from  the  .DEFAULT:  target  entry,  if  there  is  such  an  entry  in  the  makefile. 

If  there  is  no  makefile  entry  for  a  target,  if  no  rule  can  be  derived  for  building  it,  and  if  no  file  by  that  name 
is  present,  make  issues  an  error  message  and  halts. 

OPTIONS 

-f  makefile 

Use  the  description  file  makefile.  A  as  the  makefile  argument  denotes  the  standard  input.  The 
contents  of  makefile,  when  present,  override  the  standard  set  of  implicit  rules  and  predefined  mac¬ 
ros.  When  more  than  one  ‘-f  makefile^  argument  pair  appears,  make  uses  the  concatenation  of 
those  files,  in  order  of  appearance.  ^ 

-d  Display  the  reasons  why  make  chooses  to  rebuild  a  target;  make  displays  any  and  all  dependen¬ 
cies  that  are  newer.  In  addition,  make  displays  options  read  in  from  the  MAKEFLAGS  environ¬ 
ment  variable. 
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-dd  Display  the  dependency  check  and  processing  in  vast  detail. 

— D  Display  the  text  of  the  makefiles  read  in. 

— DD  Display  the  text  of  the  makefiles,  default.nik  file,  the  state  file,  and  all  hidden-dependency  reports, 

-e  Environment  variables  override  assignments  within  makefiles. 

~i  Ignore  error  codes  returned  by  commands.  Equivalent  to  the  special-function  target  ‘.IGNORE:  ’. 

-k  When  a  nonzero  error  status  is  returned  by  a  rule,  or  when  make  cannot  find  a  rule,  abandon  work 

on  the  current  target,  but  continue  with  other  dependency  branches  that  do  not  depend  on  it. 

-n  No  execution  mode.  Print  commands,  but  do  not  execute  them.  Even  lines  beginning  with  an  @ 
are  printed.  However,  if  a  command  line  contains  a  reference  to  the  $(MAKE)  macro,  that  line  is 
always  executed  (see  the  discussion  of  MAKEFLAGS  in  Reading  Makefiles  and  the  Environ¬ 
ment). 

-p  Print  out  the  complete  set  of  macro  definitions  and  target  descriptions. 

-P  Merely  report  dependencies,  rather  than  building  them. 

-q  Question  mode,  make  returns  a  zero  or  nonzero  status  code  depending  on  whether  or  not  the  tar¬ 
get  file  is  up  to  date. 

-r  Do  not  read  in  the  default  makefile  <make/default.mk>, 

-s  Silent  mode.  Do  not  print  command  lines  before  executing  them.  Equivalent  to  the  special- 
function  target  ‘.SILENT:’. 

-S  Undo  the  effect  of  the  ~k  option.  Stop  processing  when  a  non-zero  exit  status  is  returned  by  a 
command. 

“t  Touch  the  target  files  (bringing  them  up  to  date)  rathw  than  performing  their  rules.  This  can  be 
dangerous  when  files  are  maintained  by  more  than  one  person.  When  the  .KEEP_STATE:  target 
appears  in  the  makefile,  this  option  updates  the  state  file  just  as  if  the  rules  had  been  performed. 

macro  =value 

Macro  definition.  This  definition  overrides  any  regular  definition  for  the  specified  macro  within 
the  makefile  itself,  or  in  the  environment.  However,  this  definition  can  still  be  overridden  by  con¬ 
ditional  macro  assignments. 

USAGE 

Refer  to  SunOS  User's  Guide:  Doing  More  and  make  in  Programming  Utilities  and  Libraries  for  tutorial 
information  about  make. 

Reading  Makefiles  and  the  Environment 

When  make  first  starts,  it  reads  the  MAKEFLAGS  environment  variable  to  obtain  any  the  following  options 
specified  present  in  its  value:  -d,  -D,  -e,  -i,  -k,  -I,  -n,  -p,  -q,  -r,  -s,  -S,  or  -t.  (Within  the 
MAKEFLAGS  value,  the  leading  ‘ — ’  character  for  the  option  string  is  omitted.)  make  then  reads  the  com¬ 
mand  line  for  additional  options,  which  also  take  effect. 

Next,  make  reads  in  a  default  makefile  that  typically  contains  predefined  macro  definitions,  target  entries 
for  implicit  rules,  and  additional  rules,  such  as  the  rule  for  retrieving  SCCS  files.  If  present,  make  uses  the 
file  default.mk  in  the  current  directory;  otherwise  it  reads  the  file  <make/defauU.mk>,  which  contains  the 
standard  definitions  and  rules. 

Use  the  directive: 

include  <make/default.mk> 
in  your  local  default.mk  file  to  include  them. 
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Next,  make  imports  variables  from  the  environment  (unless  the  -e  option  is  in  effect),  and  treats  them  as 
defined  macros.  Because  make  uses  the  most  recent  definition  it  encounters,  a  macro  definition  in  the 
makefile  normally  overrides  an  environment  variable  of  the  same  name.  When  -e  is  in  effect,  however, 
environment  variables  are  read  in  after  all  makefiles  have  been  read.  In  that  case,  the  environment  vari¬ 
ables  take  precedence  over  definitions  in  the  makefile. 

Next,  make  reads  the  state  file,  .make,state  in  the  local  directory  if  it  exists,  and  then  any  makefiles  you 
specify  with  -f,  or  one  of  makefile  or  Makefile  as  described  above. 

Next,  (after  reading  the  environment  if  -“C  is  in  effect),  make  reads  in  any  macro  definitions  supplied  as 
command  line  arguments.  These  override  macro  definitions  in  the  makefile  and  the  environment  both,  but 
only  for  the  make  command  itself. 

make  exports  environment  variables,  using  the  most  recently  defined  value.  Macro  definitions  supplied  on 
the  command  line  are  not  normally  exported,  unless  the  macro  is  also  an  environment  variable. 

make  does  not  export  macros  defined  in  the  makefile.  If  an  environment  variable  is  set,  and  a  macro  with 
the  same  name  is  defined  on  the  command  line,  make  exports  its  value  as  defined  on  the  command  line. 
Unless  -e  is  in  effect,  macro  definitions  within  the  makefile  take  precedence  over  those  imported  from  the 
environment. 

The  macros  MAKEFLAGS,  MAKE,  KEEPSTATE,  SHELL,  HOST_ARCH,  TARGETARCH, 
HOST_MACH,  and  TARGET  MACH  are  special  cases.  See  Special-Purpose  Macros  below,  for  details. 

Makefile  Target  Entries 

A  target  entry  has  the  following  format: 

target. . .  [:!::]  [dependency] ...  [;  command] . , . 

[command] 


The  first  line  contains  the  name  of  a  target,  or  a  space-separated  list  of  target  names,  terminated  with  a 
colon  or  double  colon.  If  a  list  of  targets  is  given,  this  is  equivalent  to  having  a  separate  entry  of  the  same 
form  for  each  target.  The  colon(s)  may  be  followed  by  a  dependency ,  or  a  dependency  list,  make  checks 
this  list  before  building  the  target.  The  dependency  list  may  be  terminated  with  a  semicolon  (;),  which  in 
turn  can  be  followed  by  a  single  Bourne  shell  command.  Subsequent  lines  in  the  target  entry  begin  with  a 
TAB,  and  contain  Bourne  shell  commands.  These  commands  comprise  the  rule  for  building  the  target. 

Shell  commands  may  be  continued  across  input  lines  by  escaping  the  NEWLINE  with  a  backslash  (\).  The 
continuing  line  must  also  start  with  a  TAB. 

To  rebuild  a  target,  make  expands  macros,  strips  off  initial  TAB  characters  and  either  executes  the  com¬ 
mand  directly  (if  it  contains  no  shell  metacharacters),  or  passes  each  command  line  to  a  Bourne  shell  for 
execution. 

The  first  line  that  does  not  begin  with  a  TAB  or  #  begins  another  target  or  macro  definition. 

Makefile  Special  Characters 
Global 

#  Start  a  comment.  The  comment  ends  at  the  next  NEWLINE.  If  the  #  follows  the  TAB  in  a  com¬ 
mand  line,  that  line  is  passed  to  the  shell  (which  also  treats  #  as  the  start  of  a  comment). 

include  filename 

If  the  word  include  appears  as  the  first  seven  letters  of  a  line  and  is  followed  by  a  SPACE  or  TAB, 
the  string  that  follows  is  taken  as  a  filename  to  interpolate  at  that  line,  include  files  can  be  nested 
to  a  depth  of  no  more  than  about  16.  If  filename  is  a  macro  reference,  it  is  expanded. 
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Targets  and  Dependencies 

X  Target  list  terminator.  Words  following  the  colon  are  added  to  the  dependency  list  for  the  target 

or  targets.  If  a  target  is  named  in  more  than  one  colon-terminated  target  entry,  the  dependencies 
for  all  its  entries  are  added  to  form  that  target’s  complete  dependency  list. 

::  Target  terminator  for  alternate  dependencies.  When  used  in  place  of  a  ’  the  double-colon  allows 

a  target  to  be  checked  and  updated  with  respect  to  alternate  dependency  lists.  When  the  target  is 
out-of-date  with  respect  to  dependencies  listed  in  the  first  alternate,  it  is  built  according  to  the  rule 
for  that  entry.  When  out-of-date  with  respect  to  dependencies  in  another  alternate,  it  is  built 
according  the  rule  in  that  other  entry.  Implicit  rules  do  not  apply  to  double-colon  targets;  you 
must  supply  a  rule  for  each  entry.  If  no  dependencies  are  specified,  the  rule  is  always  performed. 

target  [+  target. . .  ] : 

Target  group.  The  rule  in  the  target  entry  builds  all  the  indicated  targets  as  a  group.  It  is  normally 
performed  only  once  per  make  run,  but  is  checked  for  command  dependencies  every  time  a  target 
in  the  group  is  encountered  in  the  dependency  scan. 

%  Pattern  matching  wild  card  metacharacter.  Like  the  shell  wild  card,  *%’  matches  any  string  of 
zero  or  more  characters  in  a  target  name  or  dependency,  in  the  target  portion  of  a  conditional 
macro  definition,  or  within  a  pattern  replacement  macro  reference.  Note:  only  one  *%’  can 
appear  in  a  target,  dependency-name,  or  pattern-replacement  macro  reference. 

Jpathname 

make  ignores  the  leading  V’  characters  from  targets  with  names  given  as  pathnames  relative  to 
“dot,”  the  working  directory. 

Macros 

=  Macro  definition.  The  word  to  the  left  of  this  character  is  the  macro  name;  words  to  the  right 
comprise  its  value.  Leading  and  trailing  white  space  characters  are  stripped  from  the  value.  A 
word  break  following  the  =  is  implied. 

$  Macro  reference.  The  following  character,  or  the  parenthesized  or  bracketed  string,  is  interpreted 
as  a  macro  reference:  make  expands  the  reference  (including  the  $)  by  replacing  it  with  the 
macro’s  value. 

() 

{  }  Macro-reference  name  delimiters.  A  parenthesized  or  bracketed  word  appended  to  a  $  is  taken  as 
the  name  of  the  macro  being  referred  to.  Without  the  delimiters,  make  recognizes  only  the  first 
character  as  the  macro  name. 

$$  A  reference  to  the  dollar-sign  macro,  the  value  of  which  is  the  character  *$’.  Used  to  pass  variable 
expressions  beginning  with  $  to  the  shell,  to  refer  to  environment  variables  which  are  expanded  by 
the  shell,  or  to  delay  processing  of  dynamic  macros  within  the  dependency  list  of  a  target,  until 
that  target  is  actually  processed. 

\$  Escaped  dollar-sign  character.  Interpreted  as  a  literal  dollar  sign  within  a  rule. 

+=  When  used  in  place  of  *=’,  appends  a  string  to  a  macro  definition  (must  be  surrounded  by  white 

space,  unlike  ‘=’). 

:=  Conditional  macro  assignment.  When  preceded  by  a  list  of  targets  with  explicit  target  entries,  the 
macro  definition  that  follows  takes  effect  when  processing  only  those  targets,  and  their  dependen¬ 
cies. 

;sh  =  Define  the  value  of  a  macro  to  be  the  output  of  a  command  (see  Command  Substitutions, 
below). 

:sh  In  a  macro  reference,  execute  the  command  stored  in  the  macro,  and  replace  the  reference  with 
the  output  of  that  command  (see  Command  Substitutions). 
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Rules 

~  make  ignores  any  nonzero  error  code  returned  by  a  command  line  for  which  the  first  non-TAB 
character  is  a  This  character  is  not  passed  to  the  shell  as  part  of  the  command  line,  make 
normally  terminates  when  a  command  returns  nonzero  status,  unless  the  -i  or  -k  options,  or  the 
.IGNORE:  special-function  target  is  in  effect. 

@  If  the  first  non-TAB  character  is  a  make  does  not  print  the  command  line  before  executing  it. 
This  character  is  not  passed  to  the  shell. 

?  Escape  command-dependency  checking.  Command  lines  starting  with  this  character  are  not  sub¬ 
ject  to  command  dependency  checking. 

!  Force  command-dependency  checking.  Command-dependency  checking  is  applied  to  command 
lines  for  which  it  would  otherwise  be  suppressed.  This  checking  is  normally  suppressed  for  lines 
that  contain  references  to  the  *?’  dynamic  macro  (for  example,  *$?’). 

When  any  combination  of  *?’,  or  *!’  appear  as  the  first  characters  after  the  TAB,  all  that  are 

present  apply.  None  are  passed  to  the  shell. 

Special-Function  Targets 

When  incorporated  in  a  makefile,  the  following  target  names  perform  special-functions: 

.DEFAULT: 

If  it  has  an  entry  in  the  makefile,  the  rule  for  this  target  is  used  to  process  a  target  when  there  is  no 
other  entry  for  it,  no  rule  for  building  it,  and  no  SCCS  history  file  from  which  to  retrieve  a  current 
version,  make  ignores  any  dependencies  for  this  target. 

.DONE:  If  defined  in  the  makefile,  make  processes  this  target  and  its  dependencies  after  all  other  targets 
are  built.  This  target  is  also  performed  when  make  halts  with  an  error,  unless  the  .FAILED  target 
is  defined. 

.FAILED: 

This  target,  along  with  its  dependencies,  is  performed  instead  of  .DONE  when  defined  in  the 
makefile  and  make  halts  with  an  error. 

.IGNORE: 

Ignore  errors.  When  this  target  appears  in  the  makefile,  make  ignores  non-zero  error  codes 
returned  from  commands. 

JNIT:  If  defined  in  the  makefile,  this  target  and  its  dependencies  are  built  before  any  other  targets  are 
processed. 

.KEEP_STATE: 

If  this  target  appears  in  the  makefile,  make  updates  the  state  file,  .make.state,  in  the  current  direc¬ 
tory.  This  target  also  activates  command  dependencies,  and  hidden  dependency  checks. 

.MAKE_VERSION: 

A  target-entry  of  the  form: 

.MAKE_VERSION:  VERSION-m/m^er 

enables  version  checking.  If  the  version  of  make  differs  from  the  version  indicated,  make  issues 
a  warning  message. 

.NO__PARALLEL: 

Currently,  this  target  has  no  effect,  it  is,  however,  reserved  for  future  use. 

.PARALLEL: 

Currently  of  no  effect,  but  reserved  for  future  use. 

.PRECIOUS: 

List  of  files  not  to  delete,  make  does  not  remove  any  of  the  files  listed  as  dependencies  for  this 
target  when  interrupted,  make  normally  removes  the  current  target  when  it  receives  an  interrupt. 
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.SCCS_GET: 

This  target  contains  the  rule  for  retrieving  the  current  version  of  an  SCCS  file  from  its  history  file. 
To  suppress  automatic  retrieval,  add  an  entry  for  this  target  with  an  empty  rule  to  your  makefile. 
.SILENT; 

Run  silently.  When  this  target  appears  in  the  makefile,  make  does  not  echo  commands  before  exe¬ 
cuting  them. 

.SUFFIXES; 

The  suffixes  list  for  selecting  implicit  rules  (see  The  Suffixes  List). 

.WAIT:  Currently  of  no  effect,  but  reserved  for  future  use. 

Clearing  Special  Targets 

In  this  version  of  make,  you  can  clear  the  definition  of  the  following  special  targets  by  supplying  entries 
for  them  with  no  dependencies  and  no  rule: 

.DEFAULT,  .SCCS^GET,  and  .SUFFIXES 

Command  Dependencies 

When  the  .KEEP  STATE:  target  appears  in  the  makefile,  make  checks  the  command  for  building  a  target 
against  the  state  file,  .make.state.  If  the  command  has  changed  since  the  last  make  run,  make  rebuilds  the 
target. 

Hidden  Dependencies 

When  the  .KEEP_STATE;  target  appears  in  the  makefile,  make  reads  reports  from  cpp(l)  and  other  compi¬ 
lation  processors  for  any  “hidden”  files,  such  as  #include  files.  If  the  target  is  out  of  date  with  respect  to 
any  of  these  files,  make  rebuilds  it. 

Macros 

Entries  of  the  form 

macro-value 

i 

define  macros,  macro  is  the  name  of  the  macro,  and  value,  which  consists  of  all  characters  up  to  a  com¬ 
ment  character  or  unescaped  NEWLINE,  is  the  value,  make  strips  both  leading  and  trailing  white  space  in 
accepting  the  value. 

Subsequent  references  to  the  macro,  of  the  forms:  or  ${name}  are  replaced  by  value.  The 

parentheses  or  brackets  can  be  omitted  in  a  reference  to  a  macro  with  a  single-character  name. 

Macro  references  can  contain  references  to  other  macros,  in  which  case  nested  references  are  expanded 
first. 

Suffix  Replacement  Macro  References 

Substitutions  within  macros  can  be  made  as  follows: 

%iname  istringl  =string2 ) 

where  stringl  is  either  a  suffix,  or  a  word  to  be  replaced  in  the  macro  definition,  and  string2  is  the  replace¬ 
ment  suffix  or  word.  Words  in  a  macro  value  are  separated  by  SPACE,  TAB,  and  escaped  NEWLINE  char¬ 
acters. 
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Pattern  Replacement  Macro  References 

Pattern  matching  replacements  can  also  be  applied  to  macros,  with  a  reference  of  the  form: 

%{namei  op%os-  np%ns) 

where  op  is  the  existing  (old)  prefix  and  os  is  the  existing  (old)  suffix,  np  and  ns  are  the  new  prefix  and  new 
suffix,  respectively,  and  the  pattern  matched  by  %  (a  string  of  zero  or  more  characters),  is  carried  forward 
from  the  value  being  replaced.  For  example: 

PROGRAM=fabricate 

DEBUG=  $(PROGRAM:%=tmp/%-g) 

sets  the  value  of  DEBUG  to  tmp/fabricate-g. 

Note:  pattern  replacement  macro  references  cannot  be  used  in  the  dependency  list  of  a  pattern  matching 
rule;  the  %  characters  are  not  evaluated  independently.  Also,  any  number  of  %  metacharacters  can  appear 
after  the  equal-sign. 

Appending  to  a  Macro 

Words  can  be  appended  to  macro  values  as  follows: 
macro  +=  word . . . 

Special-Purpose  Macros 

When  the  MAKEFLAGS  variable  is  present  in  the  environment,  make  takes  options  from  it,  in  combination 
with  options  entered  on  the  command  line,  make  retains  this  combined  value  as  the  MAKEFLAGS  macro, 
and  exports  it  automatically  to  each  command  or  shell  it  invokes. 

Note:  flags  passed  by  way  of  MAKEFLAGS  are  only  displayed  when  the  ~d,  or  -dd  options  are  in  effect. 

The  MAKE  macro  is  another  special  case.  It  has  the  value  make  by  default,  and  temporarily  overrides  the 
-n  option  for  any  line  in  which  it  is  referred  to.  This  allows  nested  invocations  of  make  written  as: 

$(MAKE)  . . . 

to  run  recursively,  with  the  -n  flag  in  effect  for  all  commands  but  make.  This  lets  you  use  ‘make  -n’  to 
test  an  entire  hierarchy  of  makefiles. 

For  compatibility  with  the  4.2  BSD  make,  the  MFLAGS  macro  is  set  from  the  MAKEFLAGS  variable  by 
prepending  a  MFLAGS  is  not  exported  automatically. 

The  SHELL  macro,  when  set  to  a  single-word  value  such  as  /usr/bin/csh,  indicates  the  name  of  an  alternate 
shell  to  use.  The  default  is  /bin/sh.  Note:  make  executes  commands  that  contain  no  shell  metacharacters 
itself.  Built-in  commands,  such  as  dirs  in  the  C  shell,  are  not  recognized  unless  the  command  line  includes 
a  metacharacter  (for  instance,  a  semicolon).  This  macro  is  neither  imported  from,  nor  exported  to  the 
environment,  regardless  of  -e.  To  be  sure  it  is  set  properly,  you  must  define  this  macro  within  every 
makefile  that  requires  it. 

The  KEEP__STATE  environment  variable  has  the  same  effect  as  the  .KEEP_STATE:  special-function  target. 
It  enables  command  dependencies,  hidden  dependencies  and  writing  of  the  state  file. 

The  following  macros  are  provided  for  use  with  cross-compilation: 

HOST^ARCH 

The  machine  architecture  of  the  host  system.  By  default,  this  is  the  output  of  the  arch(l)  com¬ 
mand  prepended  with  ‘ — ’.  Under  normal  circumstances,  this  value  should  never  be  altered  by  the 
user. 

TARGET_^ARCH 

The  machine  architecture  of  the  target  system.  By  default,  the  output  of  arch,  prepended  with 
<  > 

HOST_MACH 

The  machine  architecture  of  the  host  system.  By  default,  this  is  the  output  of  the  mach(l), 
prepended  with  * — ’.  Under  normal  circumstances,  this  value  should  never  be  altered  by  the  user. 
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TARGET_MACH 

The  machine  architecture  of  the  target  system.  By  default,  the  output  of  mach,  prepended  with 
Dynamic  Macros 

There  are  several  dynamically  maintained  macros  that  are  useful  as  abbreviations  within  rules.  They  are 
shown  here  as  references;  if  you  were  to  define  them,  make  would  simply  override  the  definition. 

$*  The  basename  of  the  current  target,  derived  as  if  selected  for  use  with  an  implicit  rule. 

$<  The  name  of  a  dependency  file,  derived  as  if  selected  for  use  with  an  implicit  rule. 

$@  The  name  of  the  current  target.  This  is  the  only  dynamic  macro  whose  value  is  strictly  determined 

when  used  in  a  dependency  list.  (In  which  case  it  takes  the  form  ‘$$@’.) 

$?  The  list  of  dependencies  that  are  newer  than  the  target.  Command-dependency  checking  is 
automatically  suppressed  for  lines  that  contain  this  macro,  just  as  if  the  command  had  been 
prefixed  with  a  *?’.  See  the  description  of under  Makefile  Special  Tokens,  above.  You  can 
force  this  check  with  the !  command-line  prefix. 

$%  The  name  of  the  library  member  being  processed,  (See  Library  Maintenance,  below.) 

To  refer  to  the  $@  dynamic  macro  within  a  dependency  list,  precede  the  reference  with  an  additional  ‘$’ 
character  (as  in,  ‘$$@’).  Because  make  assigns  $<  and  $*  as  it  would  for  implicit  rules  (according  to  the 
suffixes  list  and  the  directory  contents),  they  may  be  unreliable  when  used  within  explicit  target  entries. 

These  macros  can  be  modified  to  apply  either  to  the  filename  part,  or  the  directory  part  of  the  strings  they 
stand  for,  by  adding  an  upper  case  F  or  D,  respectively  (and  enclosing  the  resulting  name  in  parentheses  or 
braces).  Thus,  ‘$(@D)’  refers  to  the  directory  part  of  the  string  if  there  is  no  directory  part,  is 
assigned.  $(@F)  refers  to  the  filename  part. 

Conditional  Macro  Definitions 

A  macro  definition  of  the  form; 

target-list  :=  macro  =  value 

indicates  that  when  processing  any  of  the  targets  listed  and  their  dependencies  ,  macro  is  to  be  set  to  the 
value  supplied.  Note  that  if  a  conditional  macro  is  referred  to  in  a  dependency  list,  the  $  must  be  delayed 
(use  $$  instead).  Also,  target-list  may  contain  a  %  pattern,  in  which  case  the  macro  will  be  conditionally 
defined  for  all  targets  encountered  that  match  the  pattern.  A  pattern  replacement  reference  can  be  used 
within  the  value. 

You  can  temporarily  append  to  a  macro’s  value  with  a  conditional  definition  of  the  form: 
target-list  :=  macro  +=  value 
Predefined  Macros 

make  supplies  the  macros  shown  in  the  table  that  follows  for  compilers  and  their  options,  host  architec¬ 
tures,  and  other  commands.  Unless  these  macros  are  read  in  as  environment  variables,  their  values  are  not 
exported  by  make.  If  you  run  make  with  any  of  these  set  in  the  environment,  it  is  a  good  idea  to  add  com¬ 
mentary  to  the  makefile  to  indicate  what  value  each  is  expected  to  take.  If  -r  is  in  effect,  make  does  not 
read  the  default  makefile  (./defaultmk  or  <make/default,mk>)  in  which  these  macro  definitions  are  sup¬ 
plied. 
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Table  of  Predefined  Macros 

Use 

Macro 

Default  Value 

Library 

Archives 

AR 

ARFLAGS 

ar 

rv 

Assembler 

AS 

as 

Commands 

ASFLAGS 

COMPILE^ 

COMPILED 

$(AS)  $(ASFLAGS)  $(TARGET_MACH) 

$(CC)  $(ASFLAGS)  $(CPPFLAGS)  $(TARGET_MACH) -c 

C  Con^iler 
Commands 

CC 

CFLAGS 

CC 

CPPFLAGS 

COMPILE.C 

LINK.C 

$(CC)  $(CFLAGS)  $(CPPFLAGS)  -target  $(TARGET_ARCH:-%=%)  -c 
$(CC)  $(CFLAGS)  $(CPPFLAGS)  $(LDFLAGS)  -target  $(TARGET_ARCH;-%=:%) 

FORTRAN  71 

FC 

f77 

Compiler 

Commands 

FFLAGS 

COMPILE.! 

$(FC)  $(FFLAGS)  $(TARGET_ARCH) -c 

LINK.! 

COMPILE.F 

LINK.F 

$(FC)  $(FFLAGS)  $(TARGET>RCH)  $(LDFLAGS) 

$(FC)  $(FFLAGS)  $(CPPFLAGS)  $(TARGET_ARCH)  -c 

$(FC)  $(FFLAGS)  $(CPPFLAGS)  $(LDFLAGS)  $(TARGET_ARCH) 

Link  Editor 

LD 

Id 

Command 

LDFLAGS 

lex 

LEX 

lex 

Command 

LFLAGS 

LEX.1 

$(LEX)  $(LFLAGS)-t 

lint 

LINT 

lint 

Command 

LINTFLAGS 

HNT.C 

$(LINT)  $(LINTFLAGS)  $(CPPFLAGS)  $(TARGET_ARCH) 

Modulo  2 

M2C 

m2c 

Commands 

M2FLAGS 

MODFLAGS 

DEFFLAGS 

COMPILE.def 

COMPILE.mod 

$(M2C)  $(M2FLAGS)  $(DEFFLAGS)  $(TARGEn’_ARCH) 

$(M2C)  $(M2FLAGS)  $(MODFLAGS)  $(TARGET_ARCH) 

Pascal 

PC 

pc 

Compiler 

PFLAGS 

Commands 

COMPlLE.p 

LINK.P 

$(PC)  $(PFLAGS)  $(CPPFLAGS)  SCTARGETT  ARCH) -C 

$(PC)  $(PFLAGS)  $(CPPFLAGS)  $(LDFLAGS)  $(TARGET_ARCH) 

Ratfor 

RFLAGS 

Compilation 

Commands 

COMPILE.r 

LINK.r 

$(FC)  $(FFLAGS)  $(RFLAGS)  $(TARGET_ARCH) -c 

$(FC)  $(FFLAGS)  $(RFLAGS)  $(TARGET_ARCH)  $(LDFLAGS) 

rm 

Command 

RM 

rm  -f 

sees 

SCeSFLAGS 

Command 

SCeSGETFLAGS 

-s 

yacc 

Command 

YACC 

YFLAGS 

yacc 

YACC.y 

$(YACC)  $(YFLAGS) 

Suffixes 

.0  .c  .c"  .s  .s"  .S  .S"  .In  .f  .r  .F  .F"  .1 

List 

SUFFIXES 

.1"  .mod  .mod"  .sym  .def  .def  .p  .p"  .r  .r" 

.y  .y"  .h  .h“  .sh  .sh"  xps  .cps" 
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Implicit  Rules 

When  a  target  has  no  entry  in  the  makefile,  make  attempts  to  determine  its  class  (if  any)  and  apply  the  rule 
for  that  class.  An  implicit  rule  describes  how  to  build  any  target  of  a  given  class,  from  an  associated 
dependency  file.  The  class  of  a  target  can  be  determined  either  by  a  pattern,  or  by  a  suffix;  the  correspond¬ 
ing  dependency  file  (with  the  same  basename)  firom  which  such  a  target  might  be  built.  In  addition  to  a 
predefined  set  of  implicit  rules,  make  allows  you  to  define  your  own,  either  by  pattern,  or  by  suffix. 

Pattern  Matching  Rules 

A  target  entry  of  the  form: 

tp%ts:  dp%ds 
rule 

is  a  pattern  matching  rule,  in  which  tp  is  a  target  prefix,  ts  is  a  target  suffix,  dp  is  a  dependency  prefix,  and 
ds  is  a  dependency  suffix  (any  of  which  may  be  null).  The  %  stands  for  a  basename  of  zero  or  more  char¬ 
acters  that  is  matched  in  the  target,  and  is  used  to  construct  the  name  of  a  dependency.  When  make 
encounters  a  match  in  its  search  for  an  implicit  rule,  it  uses  the  rule  in  that  target  entry  to  build  the  target 
from  the  dependency  file.  Pattern-matching  implicit  rules  typically  make  use  of  the  $@  and  $<  dynamic 
macros  as  placeholders  for  the  target  and  dependency  names.  Other,  regular  dependencies  may  occur  in 
the  dependency  list.  An  entry  of  the  form: 

tp%tsi  [dependency  . . .  ]  dp  %ds  [dependency  , . .  ] 
rule 

is  a  valid  pattern  matching  rule. 

Sujfix  Rules 

When  no  pattern  matching  rule  applies,  make  checks  the  target  name  to  see  if  it  ends  with  a  suffix  in  the 
known  suffixes  list.  If  so,  make  checks  for  any  suffix  rules,  as  well  as  a  dependency  file  with  same  root 
and  another  recognized  suffix,  from  which  to  build  it. 

The  target  entry  for  a  suffix  rule  takes  the  form: 

DsTsi 

rule 

where  Ts  is  the  suffix  of  the  target,  Ds  is  the  suffix  of  the  dependency  file,  and  rule  is  the  rule  for  building  a 
target  in  the  class.  Both  Ds  and  Ts  must  appear  in  the  suffixes  list.  (A  suffix  need  not  begin  with  a  to 
be  recognized.) 

A  suffix  rule  with  only  one  suffix  describes  how  to  build  a  target  having  a  null  (or  no)  suffix  from  a  depen¬ 
dency  file  with  the  indicated  suffix.  For  instance,  the  .c  rule  could  be  used  to  build  an  executable  program 
named  file  from  a  C  source  file  named  ‘file.c\  If  a  target  with  a  null  suffix  has  an  explicit  dependency, 
make  omits  the  search  for  a  suffix  rule. 
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Table  of  Standard  Implicit  (Suffix)  Rules 

Use 

Implicit  Rule  Name 

Command  Line 

Assembly 

.5.0 

$(COMPILE.s) -o  $@$< 

Files 

.s.a 

$(COMPILE.s)  -o  $%  $< 

$(AR)  $(ARFLAGS)  $@  $% 

$(RM)  $% 

.S.O 

$(COMPILE.S)  -o  $@  $< 

.S.a 

$(COMPILE.S) -0  $%$< 

$(AR)  $(ARFLAGS)  $@$% 

$(RM)  $% 

C 

.c 

$(LINK.c)  -o  $@)  $<  $(LDLIBS) 

Files 

.c.ln 

$(LINT.c)  $(OXJTPUT_OPTION)  -i  $< 

.C.O 

$(COMPlLE.c)  $(OUTPGT_OPTION)  $< 

.c.a 

$(COMPILE.c)  -o  $%  $< 

$(AR)  $(ARFLAGS)  $@  $% 

$(RM)  $% 

FORTRAN  77 

.f 

$(LINK.O  ^  $@  $<  $(LDLIBS) 

Files 

.f.o 

$(COMPILE.f)  $(OljTPUT_OPTION)  $< 

.f.a 

$(COMPILE.f) -0  $%$< 

$(AR)  $(ARFLAGS)  $@$% 

$(RM)  $% 

.F 

$(L1NK.F)  ~o  $@  $<  $(LDLIBS) 

.Fm 

$(COMPILE.F)  $(OUTPUT^OFnON)  $< 

.F.a 

$(COMPILE.F)  ^  $%  $< 

$(AR)  $(ARFLAGS)  $@$% 

$(RM)  $% 

lex 

.1 

$(RM)  $+.c 

Files 

$(LEX.l)  $<>$+.c 

$(LINK.c)  -0  $@  $*.c  $(LDLIBS) 

$(RM)  $*.c 

.Lc 

$(RM)  $@ 

$(LEX.l)  $<>$@ 

.l.ln 

$(RM)  $+.c 
$(LEX.l)  $<>$+.c 
$(LINT.c)  -0  $@  -i  $*.c 
$(RM)  $+.c 

.1.0 

$(RM)  $+.c 
$(LEX.l)  $<>$+.c 
$(COMPILE.c) -0  $<§)$* .c 
$(RM)  $+.c 

Modula  2 

.mod 

$(COMPILE.mod)  -0  $@  -e  $@  $< 

Files 

.mod.o 

$(COMPILE.mod)  -o  $@)  $< 

.def.sym 

$(COMPILE.def)  -o  $@  $< 

News 

.cps.h 

cps  $*.cps 

Pascal 

•P 

$(LINK.p)  -o  $@  $<  $(LDLIBS) 

Files 

.p.o 

$(COMPILE.p)  $(OUTPUT_OFriON)  $< 

Ratfor 

.r 

$(LINK.r)  -o  $@  $<  $(LDLIBS) 

Files 

.r.o 

$(COMPILE.r)  $(OUTPlJT__OPTION)  $< 

.r.a 

$(COMPILE.r)  -0  $%  $< 

$(AR)  $(ARFLAGS)  $@)$% 

$(RM)  $% 
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Table  of  Standard  Implicit  (Suffix)  Rules  (continued)  1 

Use 

Implicit  Rule  Name 

Command  Line 

SCCS 

Files 

.SCCS_GET 

sees  $(SCCSFLAGS)  get  $(SCCSGETFLAGS)  $(S)  -G$@ 

Shell 

.sh 

cat  $<  >$@ 

Scripts 

chmod  i-x  $@ 

yacc 

•y 

$(YACC.y)  $< 

Files 

$(LINK.c)  -o  $@  y.tab.c  $<LDLIBS) 

$(R]VI)  y.tab.c 

•y*c 

$(YACC.y)  $< 
mv  y.tab.c  $@ 

.y.ln 

$(YACC.y)$< 

$(LINT.c)-o$@-iy.tab.c 
$(RM)  y.tab.c 

.y.o 

$(YACC.y)  $< 

$(COMPILE.c)  -0  $@  y.tab.c 
$(RM)  y.tab.c 

make  reads  in  the  standard  set  of  implicit  rules  from  the  file  <make/default.mk>,  unless  -r  is  in  effect,  or 
there  is  a  defaultmk  file  in  the  local  directory  that  does  not  include  that  file. 


The  Suffixes  List 

The  suffixes  list  is  given  as  the  list  of  dependencies  for  the  ‘.SUFFIXES:’  special-function  target.  The 
default  list  is  contained  in  the  SUFFIXES  macro  (See  Table  of  Predefined  Macros  for  the  standard  list  of 
suffixes).  You  can  define  additional  .SUFFIXES:  targets;  a  .SUFFIXES  target  with  no  dependencies  clears 
the  list  of  suffixes.  Order  is  significant  within  the  list;  make  selects  a  rule  that  corresponds  to  the  target’s 
suffix  and  the  first  dependency-file  suffix  found  in  the  list.  To  place  suffixes  at  the  head  of  the  list,  clear  the 
list  and  replace  it  with  the  new  suffixes,  followed  by  the  default  list 

.SUFFIXES; 

.SUFFIXES:  suffixes  $(SUFFIXES) 

A  tilde  ("■)  indicates  that  if  a  dependency  file  with  the  indicated  suffix  (minus  the  ”)  is  under  SCCS  its  most 
recent  version  should  be  retrieved,  if  necessary,  before  the  target  is  processed. 

Library  Maintenance 

A  target  name  of  the  form: 

lib  (member . , 

refers  to  a  member,  or  a  space-separated  list  of  members,  in  an  ar(l  V)  library. 

The  dependency  of  the  library  member  on  the  corresponding  file  must  be  given  as  an  explicit  entry  in  the 
makefile.  This  can  be  handled  by  a  pattern  matching  rule  of  the  form: 

lib(%.s):  %.s 

where  .s  is  the  suffix  of  the  member;  this  suffix  is  typically  .o  for  object  libraries. 

A  target  name  of  the  form 
lib{(symbol)) 

refers  to  the  member  of  a  randomized  object  library  (see  ranlib(l))  that  defines  the  entry  point  named  sym¬ 
bol. 
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Command  Execution 

Command  lines  are  executed  one  at  a  time,  each  by  its  own  process  or  shell  Shell  commands,  notably  cd, 
are  ineffectual  across  an  unescaped  NEWLINE  in  the  makefile.  A  line  is  printed  (after  macro  expansion) 
just  before  being  executed.  This  is  suppressed  if  it  starts  with  a  if  there  is  a  ‘.SILENT:’  entry  in  the 
makefile,  or  if  make  is  run  with  the  -s  option.  Although  the  -n  option  specifies  printing  without  execu¬ 
tion,  lines  containing  the  macro  $(MAKE)  are  executed  regardless,  and  lines  containing  the  @  special  char¬ 
acter  are  printed.  The  -t  (touch)  option  updates  the  modification  date  of  a  file  without  executing  any  rules. 
This  can  be  dangerous  when  sources  are  maintained  by  more  than  one  person. 

Bourne  Shell  Constructs 

To  use  the  Bourne  shell  if  control  structure  for  branching,  use  a  command  line  of  the  form: 

if  expression  ;  \ 
then  command  ;  \ 

...;\ 

else ;  \ 
fi 

Although  composed  of  several  input  lines,  the  escaped  NEWLINE  characters  insure  that  make  treats  them 
all  as  one  (shell)  command  line. 

To  use  the  Bourne  shell  for  control  structure  for  loops,  use  a  command  line  of  the  form: 

for  var  in  list  ;  \ 

do  command;  \ 

...;\ 

done 

To  refer  to  a  shell  variable,  use  an  escaped  dollar-sign  (\$).  This  prevents  expansion  of  the  dollar-sign  by 

make. 

Command  Substitutions 

To  incorporate  the  standard  output  of  a  shell  command  in  a  macro,  use  a  definition  of  the  form: 

MACRO  :sh  ^command 

The  command  is  executed  only  once,  standard  error  output  is  discarded,  and  NEWLINE  characters  are 
replaced  with  SPACEs.  If  the  command  has  a  non-zero  exit  status,  make  halts  with  an  error. 

To  capture  the  output  of  a  shell  command  in  a  macro  reference,  use  a  reference  of  the  form: 

${MACRO  :sh) 

where  MACRO  is  the  name  of  a  macro  containing  a  valid  Bourne  shell  command  line.  In  this  case,  the  com¬ 
mand  is  executed  whenever  the  reference  is  evaluated.  As  with  shell  command  substitutions,  the  reference 
is  replaced  with  the  standard  output  of  the  command.  If  the  command  has  a  non-zero  exit  status,  make 
halts  with  an  error. 

Signals 

INT  and  QUIT  signals  received  from  the  keyboard  halt  make  and  remove  the  target  file  being  processed 
unless  that  target  is  in  the  dependency  list  for  ‘.PRECIOUS:’. 
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EXAMPLES 

This  makefile  says  that  pgm  depends  on  two  files  a.o  and  b.o,  and  that  they  in  turn  depend  on  their 
corresponding  source  files  (a.c  and  b,c)  along  with  a  common  file  incLh: 

pgm:  a.o  b.o 

$(LINK.c)  -o  $(S)  a.o  b.o 

a. o:  incl.h  a.c 

cc  ~c  a.c 

b. o:  incLh  b.c 

cc  -c  b.c 

The  following  makefile  uses  implicit  rules  to  express  the  same  dependencies: 

pgm:  a.o  b.o 

cc  a.o  b.o  -o  pgm 
a.o  b.o:  incLh 

FILES 

makefile 
Makefile 
SCCS/s.makefile 
SCCS/s.Makefile 
default.mk 
<make/default.mk> 

.make.state 

SEE  ALSO 

ar(lV),  cc(lV),  cd(l),  sccs-get(l),  lex(l),  ranlib(l),  passwd(5) 

SunOS  User's  Guide:  Doing  More 
Programming  Utilities  and  Libraries 

DIAGNOSTICS 

make  returns  an  exit  status  of  1  when  it  halts  as  a  result  of  an  error.  Otherwise  it  returns  an  exit  status  of  0. 
Do  not  know  how  to  make  target.  Stop. 

There  is  no  makefile  entry  for  target,  and  none  of  make’s  implicit  rules  apply  (there  is  no  depen> 
dency  file  with  a  suffix  in  the  suffixes  list»  or  the  target’s  suffix  is  not  in  the  list). 

**+  target  removed. 

make  was  interrupted  while  building  target.  Rather  than  leaving  a  partially-completed  version 
that  is  newer  than  its  dependencies,  make  removes  the  file  named  target. 

***  target  not  removed. 

make  was  interrupted  while  building  target  and  target  was  not  present  in  the  directory. 

+**  target  could  not  be  removed,  reason 

make  was  interrupted  while  building  target,  which  was  not  removed  for  the  indicated  reason. 
Read  of  include  file  failed 

The  makefile  indicated  in  an  include  directive  was  not  found,  or  was  inaccessible. 

Loop  detected  when  expanding  macro  value  ^macro  * 

A  reference  to  the  macro  being  defined  was  found  in  the  definition. 

Could  not  write  state  file  ^file' 

You  used  the  ,KEEP_STATE;  target,  but  do  not  have  write  permission  on  the  state  file. 

***  Error  code  n 

The  previous  shell  command  returned  a  nonzero  eiror  code. 


current  version(s)  of  make  description  file 

sees  history  files  for  the  above  makefile(s) 

default  file  for  user-defined  targets,  macros,  and  implicit  rules 

makefile  for  standard  implicit  rules  and  macros  (not  read  if  default.mk  is) 

state  file  in  the  local  directory 
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***  signal  message 

The  previous  shell  command  was  aborted  due  to  a  signal.  If  core  dumped’  appears  after  the 
message,  a  core  file  was  created. 

Conditional  macro  conflict  encountered 

Displayed  only  when  -d  is  in  effect,  this  message  indicates  that  two  or  more  parallel  targets 
currently  being  processed  depend  on  a  target  which  is  built  differently  for  each  by  virtue  of  condi¬ 
tional  macros.  Since  the  target  cannot  simultaneously  satisfy  both  dependency  relationships,  it  is 
conflicted. 

BUGS 

Some  commands  return  nonzero  status  inappropriately;  to  overcome  this  difficulty,  prefix  the  offending 
command  line  in  the  rule  with  a 

Filenames  with  the  characters  ‘=’,  or  do  not  work. 

You  cannot  build  file.o  from  lib(file.o). 

Options  supplied  by  MAKEFLAGS  should  be  reported  for  nested  make  commands.  Use  the  -d  option  to 
find  out  what  options  the  nested  command  picks  up  from  MAKEFLAGS. 

This  version  of  make  is  incompatible  in  certain  respects  with  previous  versions: 

•  The  -d  option  output  is  much  briefer  in  this  version,  -dd  now  produces  the  equivalent 
voluminous  output. 

•  make  attempts  to  derive  values  for  the  dynamic  macros  '$<’,  and  *$?’,  while  processing 
explicit  targets.  It  uses  the  same  method  as  for  implicit  rules;  in  some  cases  this  can  lead 
either  to  unexpected  values,  or  to  an  empty  value  being  assigned.  (Actually,  this  was  true  for 
earlier  versions  as  well,  even  though  the  documentation  stated  otherwise.) 

•  make  no  longer  searches  the  current  directory  for  SCCS  history  files. 

•  Suffix  replacement  in  macro  references  are  now  applied  after  the  macro  is  expanded. 

There  is  no  guarantee  that  makefiles  created  for  this  version  of  make  will  work  with  earlier  versions. 

If  there  is  no  defaultmk  file  in  the  current  directory,  and  the  file  <make/default.mk>  is  missing,  make 
stops  before  processing  any  targets.  To  force  make  to  run  anyway,  create  an  empty  default.mk  file  in  the 
current  directory. 

Once  a  dependency  is  made,  make  assumes  the  dependency  file  is  present  for  the  remainder  of  the  run.  If 
a  rule  subsequently  removes  that  file  and  future  targets  depend  on  its  existence,  unexpected  errors  may 
result. 

When  hidden  dependency  checking  is  in  effect,  the  $?  macro’s  value  includes  the  names  of  hidden  depen¬ 
dencies.  This  can  lead  to  improper  filename  arguments  to  commands  when  $?  is  used  in  a  rule. 

Pattern  replacement  macro  references  cannot  be  used  in  the  dependency  list  of  a  pattern  matching  rule. 

Unlike  previous  versions,  this  version  of  make  strips  a  leading  V’  from  the  value  of  the  ‘$(5)’  dynamic 
macro. 

With  automatic  SCCS  retrieval,  this  version  of  make  does  not  support  tilde  suffix  rules. 

The  only  dynamic  macro  whose  value  is  strictly  determined  when  used  in  a  dependency  list  is  (lakes 
the  form  ‘$$@’). 

make  invokes  the  shell  with  the  -e  (exit-on-eirors)  argument.  Thus,  with  semicolon-separated  command 
sequences,  execution  of  the  later  commands  depends  on  the  success  of  the  former.  This  is  consistent  with 
make’s  behavior  of  halting  immediately  when  a  problem  occurs,  but  cannot  be  inferred  from  the  syntax  of 
the  rule  alone. 
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NAME 

man  -  display  reference  manual  pages;  find  reference  pages  by  keyword 
SYNOPSIS 

man  [-]  [-t]  [-M path ]  [-T  macro-package  ]  [[section  ]  title 
man  [-M  path  ]  -k  keyword . . . 
man  [-M  path  ]  -f filename  . . . 

DESCRIPTION 

man  displays  information  from  the  reference  manuals.  It  can  display  complete  manual  pages  that  you 
select  by  title,  or  one-line  summaries  selected  either  by  keyword  (-k),  or  by  the  name  of  an  associated  file 
(-0- 

A  section,  when  given,  applies  to  the  titles  that  follow  it  on  the  command  line  (up  to  the  next  section,  if 
any),  man  looks  in  the  indicated  section  of  the  manual  for  those  titles,  section  is  either  a  digit  (perhaps 
followed  by  a  single  letter  indicating  the  type  of  manual  page),  or  one  of  the  words  new,  local,  old,  or  pub¬ 
lic.  The  abbreviations  n,  1,  o  and  p  are  also  allowed.  If  section  is  omitted,  man  searches  all  reference  sec¬ 
tions  (giving  preference  to  commands  over  functions)  and  prints  the  first  manual  page  it  finds.  If  no 
manual  page  is  located,  man  prints  an  error  message. 

The  reference  page  sources  are  typically  located  in  the  /usr/man/man?  directories.  Since  these  directories 
are  optionally  installed,  they  may  not  reside  on  your  host;  you  may  have  to  mount  /usr/man  from  a  host  on 
which  they  do  reside.  If  there  are  preformatted,  up-to-date  versions  in  corresponding  cat?  or  fmt?  direc¬ 
tories,  man  simply  displays  or  prints  those  versions.  If  the  preformatted  version  of  interest  is  out  of  date  or 
missing,  man  reformats  it  prior  to  display.  If  directories  for  the  preformatted  versions  are  not  provided, 
man  reformats  a  page  whenever  it  is  requested;  it  uses  a  temporary  file  to  store  the  formatted  text  during 
display. 

If  the  standard  output  is  not  a  terminal,  or  if  the  flag  is  given,  man  pipes  its  output  through  cat(l  V). 
Otherwise,  man  pipes  its  output  through  more(l)  to  handle  paging  and  underlining  on  the  screen. 

OPTIONS 

-t  man  arranges  for  the  specified  manual  pages  to  be  trolTed  to  a  suitable  raster  output  device  (see 
troff(l)  or  vtroff(l)).  If  both  the  ~  and  -t  flags  are  given,  man  updates  the  troffed  versions  of 
each  named  title  (if  necessary),  but  does  not  display  them. 

-M  path 

Change  the  search  path  for  manual  pages,  path  is  a  colon-separated  list  of  directories  that  contain 
manual  page  directory  subtrees.  For  example,  /usr/man/u_man:/usr/man/a_man  makes  man 
search  in  the  standard  System  V  locations.  When  used  with  the  -k  or  -f  options,  the  -M  option 
must  appear  first.  Each  directory  in  the  path  is  assumed  to  contain  subdirectories  of  the  form 

man[l-81-p]. 

— T  macro-package 

man  uses  macro-package  rather  than  the  standard  -man  macros  defined  in  /usr/lib/tmac/tmac.an 
for  formatting  manual  pages. 

-k  keyword . . . 

man  prints  out  one-line  summaries  from  the  whatis  database  (table  of  contents)  that  contain  any 
of  the  given  keywords.  The  whatis  database  is  created  using  the  catman(8)  command  with  the 
“W  option. 

-(filename . . . 

man  attempts  to  locate  manual  pages  related  to  any  of  the  given  filenames.  It  strips  the  leading 
pathname  components  from  each  filename,  and  then  prints  one-line  summaries  containing  the 
resulting  basename  or  names.  This  option  also  uses  the  whatis  database. 
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MANUAL PAGES 

Manual  pages  are  troff(l)/nroff(l)  source  files  prepared  with  the  -man  macro  package.  Refer  to  man(7), 
or  Formatting  Documents  for  more  information. 

When  formatting  a  manual  page,  man  examines  the  first  line  to  determine  whether  it  requires  special  pro¬ 
cessing. 

Referring  to  Other  Manual  Pages 

If  the  first  line  of  the  manual  page  is  a  reference  to  another  manual  page  entry  fitting  the  pattern: 

.so  man.?*/  sourcefile 

man  processes  the  indicated  file  in  place  of  the  current  one.  The  reference  must  be  expressed  as  a  path¬ 
name  relative  to  the  root  of  the  manual  page  directory  subtree. 

When  the  second  or  any  subsequent  line  starts  with  .so,  man  ignores  it;  troff(l)  or  nroff(l)  processes  the 
request  in  the  usual  manner. 

Preprocessing  Manual  Pages 

If  the  first  line  is  a  string  of  the  form: 

'\"  X 


where  X  is  separated  from  the  by  a  single  SPACE  and  consists  of  any  combination  of  characters  in  the 
following  list,  man  pipes  its  input  to  troff(l)  or  nroff(l)  through  the  corresponding  preprocessors. 

e  eqn(l),  or  neqn  for  nroff 

r  refer(l) 

t  tbl(l) 

V  vgrind(l) 

If  eqn  or  neqn  is  invoked,  it  will  automatically  read  the  file  /usr/pub/eqnchar  (see  eqnchar(7)).  If 
nroff(l)  is  invoked,  col(lV)  is  automatically  used. 


ENVIRONMENT 

MANPATH  If  set,  its  value  overrides  /usr/man  as  the  default  search  path.  (The  -M  flag,  in  turn, 
overrides  this  value.) 

PAGER  A  program  to  use  for  interactively  delivering  man’s  output  to  the  screen.  If  not  set, 

‘more  -s’  (see  more(I))  is  used. 

TCAT  The  name  of  the  program  to  use  to  display  troffed  manual  pages.  If  not  set,  ‘Ipr  -t’  (see 

Ipr(l))  is  used. 


FILES 


TROFF  The  name  of  the  formatter  to  use  when  the  -t  flag  is  given.  If  not  set,  troff  is  used. 


/usr/[share]/man 

/usr/[share]/man/man?/* 

/usr/[share]/man/cat?/* 

/usr/[share]/man/fmt?/* 

/usr/[share]/maii/whatis 

/usr/[share]/lib/tmac/tmac.an 

/usr/pub/eqnchar 


root  of  the  standard  manual  page  directory  subtree 

unformatted  manual  entries 

nroffed  manual  entries 

troffed  manual  entries 

table  of  contents  and  keyword  database 

standard  -man  macro  package 


SEE  ALSO 

apropos(l),  cat(lV),  col(lV),  eqn(l),  Ipr(l),  more(l),  nroff(l),  refer(l),  tbl(l),  troff(l),  vgrind(l), 
vtroff(l),  whatis(l),  eqnchar(7),  man(7),  catman(8) 
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NOTES 


BUGS 


Because  troff  is  not  8-bit  clean,  man  has  not  been  made  8-bit  clean. 

The  “f  and  -k  options  use  the  /usr/man/whatis  database,  which  is  created  by  catman(8). 


The  manual  is  supposed  to  be  reproducible  either  on  a  phototypesetter  or  on  an  ASCn  terminal.  However, 
on  a  terminal  some  information  (indicated  by  font  changes,  for  instance)  is  necessarily  lost. 

Some  dumb  terminals  cannot  process  the  vertical  motions  produced  by  the  e  (eqn(l))  preprocessing  flag. 
To  prevent  garbled  output  on  these  terminals,  when  you  use  e  also  use  t,  to  invoke  col(lV)  implicitly.  This 
workaround  has  the  disadvantage  of  eliminating  superscripts  and  subscripts  —  even  on  those  terminals  that 
can  display  them.  CTRL-Q  will  clear  a  terminal  that  gets  confused  by  eqn(l)  output. 
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NAME 


mesg  -  permit  or  deny  messages  on  the  terminal 


SYNOPSIS 

inesg[n][y] 

DESCRIPTION 

mesg  with  argument  n  forbids  messages  with  write(l)  by  revoking  non-user  write  permission  on  the  user’s 
terminal,  mesg  with  argument  y  reinstates  permission.  All  by  itself,  mesg  reports  the  current  state  without 
changing  it. 


FILES 

/dev/tty* 

SEE  ALSO 

write(l),  talk(l) 

DIAGNOSTICS 

Exit  status  is  0  if  messages  are  receivable,  1  if  not,  2  on  error. 
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NAME 

mkdir-  make  a  directory 
SYNOPSIS 

mkdir  [  ~p  ]  dirname. . . 

DESCRIPTION 

mkdir  creates  directories.  Standard  entries,  for  the  directory  itself,  and  for  its  parent,  are  made 
automatically. 

The  -p  flag  allows  missing  parent  directories  to  be  created  as  needed. 

With  the  exception  of  the  set-gid  bit,  the  current  umask(2V)  setting  determines  the  mode  in  which  direc¬ 
tories  are  created.  The  new  directory  inherits  the  set-gid  bit  of  the  parent  directory.  Modes  may  be 
modified  after  creation  by  using  chmod(l  V). 

mkdir  requires  write  permission  in  the  parent  directory. 

SEE  ALSO 

chmod(lV),  rm(l),  mkdir(2V),  umask(2V) 


(  ] 
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NAME 

mkstr  -  create  an  error  message  file  by  massaging  C  source  files 
SYNOPSIS 

mkstr  [  -  ]  messagefile  prefix  filename.. . 

DESCRIPTION 

mkstr  creates  files  of  error  messages.  You  can  use  mkstr  to  make  programs  with  large  numbers  of  error 
diagnostics  much  smaller,  and  to  reduce  system  overhead  in  running  the  program  —  as  the  error  messages 
do  not  have  to  be  constantly  swapped  in  and  out. 

mkstr  processes  each  of  the  specified  filenames,  placing  a  massaged  version  of  the  input  file  in  a  file  with  a 
name  consisting  of  the  specified  prefix  and  the  original  source  file  name.  A  typical  example  of  using  mkstr 
would  be: 

mkstr  pistrings  processed 

This  command  would  cause  all  the  error  messages  from  the  C  source  files  in  the  current  directory  to  be 
placed  in  the  file  pistrings  and  processed  copies  of  the  source  for  these  files  to  be  placed  in  files  whose 
names  are  prefixed  with  processed. 

To  process  the  error  messages  in  the  source  to  the  message  file,  mkstr  keys  on  the  string  ‘  error (”  ’  in  the 
input  stream.  Each  time  it  occurs,  the  C  string  starting  at  the  ’  is  placed  in  the  message  file  followed  by  a 
null  character  and  a  NEWLINE  character;  the  null  character  terminates  the  message  so  it  can  be  easily  used 
when  retrieved,  the  NEWLINE  character  makes  it  possible  to  sensibly  cat  ibe  error  message  file  to  see  its 
contents.  The  massaged  copy  of  the  input  file  then  contains  a  Iseek  pointer  into  the  file  which  can  be  used 
to  retrieve  the  message,  that  is: 

char  efilname[  ]  =  "/usr/lib/pi_strings"  j 
int  efil  =  -l; 

errorfal,  a2,  a3,  a4) 

{ 

char 

buf[256]; 

if(efil<0){ 

efil  =  open(efilname,  0); 
if(efil<0){ 

oops: 

perror  (efilname); 
exit  (1); 

} 

} 

if  (lseek(efil,  (long)  al,  0)  1 1  read(efil,  buf,  256)  <=  0) 
goto  oops; 

printf(buf,  a2,  a3,  a4); 

} 

OPTIONS 

~  Place  error  messages  at  the  end  of  the  specified  message  file  for  recompiling  part  of  a  large  mkstred 
program. 

SEE  ALSO 

xstr(l) 
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NAME 

more,  page  -  browse  or  page  through  a  text  file 
SYNOPSIS 

more  [  --cdfisu  ]  [  -lines  ]  [  +lmenumber  ]  [  +( pattern  ]  [filename  , . .  ] 
page  [ -cdflsu ]  [ -lines ]  [  +linenumber ]  [  +! pattern  ]  [filename  ...] 

DESCRIPTION 

more  is  a  filter  that  displays  the  contents  of  a  text  file  on  the  terminal,  one  screenful  at  a  lime.  It  normally 
pauses  after  each  screenful,  and  prints  -More-  at  the  bottom  of  the  screen,  more  provides  a  two-line 
overlap  between  screens  for  continuity.  If  more  is  reading  from  a  file  rather  than  a  pipe,  the  percentage  of 
characters  displayed  so  far  is  also  shown. 

more  scrolls  up  to  display  one  more  line  in  response  to  a  RETURN  character,  it  displays  another  screenful 
in  response  to  a  SPACE  character.  Other  commands  are  listed  below, 

page  clears  the  screen  before  displaying  the  next  screenful  of  text;  it  only  provides  a  one-line  overlap 
between  screens. 

more  sets  the  terminal  to  noecho  mode,  so  that  the  output  can  be  continuous.  Commands  that  you  type  do 
not  normally  show  up  on  your  terminal,  except  for  the  /  and  !  commands. 

If  the  standard  output  is  not  a  terminal,  more  acts  just  like  cat(l  V),  except  that  a  header  is  printed  before 
each  file  in  a  series. 

OPTIONS 

-c  Clear  before  displaying.  Redrawing  the  screen  instead  of  scrolling  for  faster  displays.  This  option 
is  ignored  if  the  terminal  does  not  have  the  ability  to  clear  to  the  end  of  a  line. 

-d  Display  error  messages  rather  than  ringing  the  terminal  bell  if  an  unrecognized  command  is  used. 
This  is  helpful  for  inexperienced  users. 

-f  Do  not  fold  long  lines.  This  is  useful  when  lines  contain  nonprinting  characters  or  escape 
sequences,  such  as  those  generated  when  nroff(l)  output  is  piped  through  ul(l), 

—I  Do  not  treat  FORMFEED  characters  (CTRL-D)  as  “page  breaks.”  If  -1  is  not  used,  more  pauses  to 
accept  commands  after  any  line  containing  a  "L  character  (CTRL-D).  Also,  if  a  file  begins  with  a 
FORMFEED,  the  screen  is  cleared  before  the  file  is  printed. 

-s  Squeeze.  Replace  multiple  blank  lines  with  a  single  blank  line.  This  is  helpful  when  viewing 
nroff(l)  output,  on  the  screen. 

”U  Suppress  generation  of  underlining  escape  sequences.  Normally,  more  handles  underlining,  such 
as  that  produced  by  nrofT(l),  in  a  manner  appropriate  to  the  terminal.  If  the  terminal  can  perform 
underlining  or  has  a  stand-out  mode,  more  supplies  appropriate  escape  sequences  as  called  for  in 
the  text  file. 

-lines  Display  the  indicated  number  of  lines  in  each  screenful,  rather  than  the  default  (the  number  of 
lines  in  the  terminal  screen  less  two). 

+linenumber 

S  tart  up  at  linenumber . 

+lpattern 

Stan  up  two  lines  above  the  line  containing  the  regular  expression  pattern.  Note:  unlike  editors, 
this  construct  should  not  end  with  a  7’.  If  it  does,  then  the  trailing  slash  is  taken  as  a  character  in 
the  search  pattern. 


Sun  Release  4.1 


Last  change:  9  September  1987 


345 


MORE(l) 


USER  COMMANDS 


MORE(l) 


USAGE 

Environment 

more  uses  the  terminal’s  termcap(5)  entry  to  determine  its  display  characteristics,  and  looks  in  the 
environment  variable  MORE  for  any  preset  options.  For  instance,  to  page  through  files  using  the  -c  mode 
by  default,  set  the  value  of  this  variable  to  -c.  (Normally,  the  command  sequence  to  set  up  this  environ¬ 
ment  variable  is  placed  in  the  .login  or  .profile  file). 

Commands 

The  commands  take  effect  immediately;  it  is  not  necessary  to  type  a  carriage  return.  Up  to  the  time  when 
the  command  character  itself  is  given,  the  user  may  type  the  line  kill  character  to  cancel  the  numerical 
argument  being  formed.  In  addition,  the  user  may  type  the  erase  character  to  redisplay  the  *-More-- 
{xx%y  message. 

In  the  following  commands,  i  is  a  numerical  argument  (1  by  default). 

/ SPACE  Display  another  screenful,  or  i  more  lines  if  i  is  specified. 

^RETURN  Display  another  line,  or  i  more  lines,  if  specified. 

i*D  (CTRL-D)  Display  (scroll  down)  1 1  more  lines,  i  is  given,  the  scroll  size  is  set  to  i . 

Same  as  *D. 

zz  Same  as  SPACE,  except  that  i ,  if  present,  becomes  the  new  default  number  of  lines  per  screen¬ 

ful. 

zs  Skip  z  lines  and  then  print  a  screenful. 

zT  Skip  z  screenfuls  and  then  print  a  screenful. 

z*B  (CTRL-B)  Skip  back  i  screenfuls  and  then  print  a  screenful. 

b  Same  as  "B  (CTRL-D). 

q 

Q  Exit  from  more. 

=  Display  the  current  line  number. 

V  Drop  into  the  vi(l)  editor  at  the  current  line  of  the  current  file, 

h  Help.  Give  a  description  of  all  the  more  commands. 

ilpattern  Search  for  the  i  th  occurrence  of  the  regular  expression  pattern.  Display  the  screenful  starting 
two  lines  prior  to  the  line  that  contains  the  z  th  match  for  the  regular  expression  pattern,  or  the 
end  of  a  pipe,  whichever  comes  first.  If  more  is  displaying  a  file  and  there  is  no  such  match, 
its  position  in  the  file  remains  unchanged.  Regular  expressions  can  be  edited  using  erase  and 
kill  characters.  Erasing  back  past  the  first  column  cancels  the  search  command, 

zn  Search  for  the  i  th  occurrence  of  the  last  pattern  entered. 

Single  quote.  Go  to  the  point  from  which  the  last  search  started.  If  no  search  has  been  per¬ 
formed  in  the  current  file,  go  to  the  beginning  of  the  file, 

Icommand  Invoke  a  shell  to  execute  command .  The  characters  %  and  !,  when  used  within  command  are 
replaced  with  the  current  filename  and  the  previous  shell  command,  respectively.  If  there  is  no 
current  filename,  %  is  not  expanded.  Prepend  a  backslash  to  these  characters  to  escape  expan¬ 
sion. 

i:n  Skip  to  the  i  th  next  filename  given  in  the  command  line,  or  to  the  last  filename  in  the  list  if  z  is 

out  of  range. 

i;p  Skip  to  the  z  th  previous  filename  given  in  the  command  line,  or  to  the  first  filename  if  z  is  out 

of  range.  If  given  while  more  is  positioned  within  a  file,  go  to  the  beginning  of  the  file.  If 
more  is  reading  from  a  pipe,  more  simply  rings  the  terminal  bell. 
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:f  Display  the  current  filename  and  line  number. 


jq 

:Q  Exit  from  more  (same  as  q  or  Q ). 

.  Dot.  Repeat  the  previous  command. 

A  . 

\  Halt  a  partial  display  of  text,  more  stops  sending  output,  and  displays  the  usual  -More- 

prompt.  Unfortunately,  some  output  is  lost  as  a  result. 

FILES 

/etc/termcap  terminal  data  base 

/usr/lib/more.he]p  help  file 


SEE  ALSO 

cat(lV),  csh(l),  maii(l),  script(l),  sh(l),  environ(5V),  termcap(5) 

BUGS 

Skipping  backwards  is  too  slow  on  large  files. 


Sun  Release  4.1 


Last  change:  9  September  1987 


347 


MT(1) 


USER  COMMANDS 


MT(1) 


NAME 

mt  -  magnetic  tape  control 
SYNOPSIS 

mt  [  -f  tapename  ]  command  [  count  ] 

DESCRIPTION 

mt  sends  commands  to  a  magnetic  tape  drive.  If  tapename  is  not  specified,  the  environment  variable  TAPE 
is  used.  If  TAPE  does  not  exist,  mt  uses  the  device  /dev/rmtl2.  tapename  refers  to  a  raw  tape  device.  By 
default,  mt  performs  the  requested  operation  once;  multiple  operations  may  be  performed  by  specifying 
count. 

The  available  commands  are  listed  below.  Only  as  many  characters  as  are  required  to  uniquely  identify  a 
command  need  be  specified. 

mt  returns  a  0  exit  status  when  the  operation(s)  were  successful,  1  if  the  command  was  unrecognized  or  if 
mt  was  unable  to  open  the  specified  tape  drive,  and  2  if  an  operation  failed. 

OPTIONS 

eof,  vpeof  Write  count  EOF  marks  at  the  current  position  on  the  tape. 

fsf  Forward  space  over  count  EOF  marks.  The  tape  is  positioned  on  the  first  block  of  the  file, 

fsr  Forward  space  count  records. 

bsf  Back  space  over  count  EOF  marks.  The  tape  is  positioned  on  the  beginning-of-tape  side  of 

the  EOF  mark. 

bsr  Back  space  count  records. 

nbsf  Back  space  count  files.  The  tape  is  positioned  on  the  first  block  of  the  file.  This  is 

equivalent  to  count+1  bsfs  followed  by  one  fsf. 

asf  Absolute  space  to  count  file  number.  This  is  equivalent  to  a  rewind  followed  by  a  fsf 

count. 


For  the  following  commands,  count  is  ignored: 

eom  Space  to  the  end  of  recorded  media  on  the  tape.  This  is  useful  for  appending  files  onto  pre¬ 

viously  written  tapes. 

rewind  Rewind  the  tape. 


FILES 


offline,  rewoffl  Rewind  the  tape  and,  if  appropriate,  take  the  drive  unit  off-line  by  unloading  the  tape, 
status  Print  status  information  about  the  tape  unit. 

retension  Rewind  the  cartridge  tape  completely,  then  wind  it  forward  to  the  end  of  the  reel  and  back 
to  beginning-of-tape  to  smooth  out  tape  tension. 

erase  Erase  the  entire  tape. 


/dev/rmt*  magnetic  tape  interface 

/dev/rar*  Archive  cartridge  tape  interface 

/dev/rst*  SCSI  tape  interface 


SEE  ALSO 

ar(4S),  mtio(4),  st(4S),  tm(4S),  xt(4S)  environ(5V) 


BUGS 

Not  all  devices  support  all  options.  Some  options  are  hardware-dependent.  Refer  to  the  corresponding 
device  manual  page. 
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WARNINGS 

The  bsf  option  for  SCSI  tape  in  SunOS  4.0.3  is  incompatible  with  this  release  and  releases  prior  to  4.0,3, 
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NAME 

mv  -  move  or  rename  files 
SYNOPSIS 

mv  [  -  ]  [  --fi  ]  filename J  filename2 
mv  [  -  ]  [  -fi  ]  directory!  directory! 
mv  [  -  ]  [  -fi }  filename . , .  directory 

DESCRIPTION 

mv  moves  files  and  directories  around  in  the  file  system.  A  side  effect  of  mv  is  to  rename  a  file  or  direc¬ 
tory.  The  three  major  forms  of  mv  are  shown  in  the  synopsis  above. 

The  first  form  of  mv  moves  (changes  the  name  of)  filename!  to  filename!.  If  filename!  already  exists,  it  is 
removed  before  filename!  is  moved.  If  fdename!  has  a  mode  which  forbids  writing,  mv  prints  the  mode 
(see  chmod(2V))  and  reads  the  standard  input  to  obtain  a  line;  if  the  line  begins  with  y,  the  move  takes 
place,  otherwise  mv  exits. 

The  second  form  of  mv  moves  (changes  the  name  of)  directory!  to  directory! ,  only  if  directory!  does  not 
already  exist  —  if  it  does,  the  third  form  applies. 

The  third  form  of  mv  moves  one  or  more  filenames  (may  also  be  directories)  with  their  original  names,  into 
the  last  directory  in  the  list. 

mv  refuses  to  move  a  file  or  directory  onto  itself. 

OPTIONS 

-  Interpret  all  the  following  arguments  to  mv  as  file  names.  This  allows  file  names  starting  with 
minus. 

-f  Force.  Override  any  mode  restrictions  and  the  -i  option.  The  -f  option  also  suppresses  any  warn¬ 
ing  messages  about  modes  which  would  potentially  restrict  overwriting. 

-i  Interactive  mode,  mv  displays  the  name  of  the  file  or  directory  followed  by  a  question  mark 
whenever  a  move  would  replace  an  existing  file  or  directory.  If  you  type  a  line  starting  with  y,  mv 
moves  the  specified  file  or  directory,  otherwise  mv  does  nothing  with  that  file  or  directory. 

SEE  ALSO 

cp(l),  In(lV),  chmod(2V),  rename(2V) 

DIAGNOSTICS 

mv:  pathname :  rename:  Permission  denied 

Attempted  to  move  pathname  into  a  directory  that  did  not  have  write  permission. 

BUGS 

If  filename!  and  filename!  are  on  different  file  systems,  then  mv  must  copy  the  file  and  delete  the  original. 
In  this  case  the  owner  name  becomes  that  of  the  copying  process  and  any  linking  relationship  with  other 
files  is  lost. 

Modification  times  may  be  different  than  expected  when  mv  must  copy  the  file’s  data,  rather  than  simply 
updating  a  directory  entry. 

mv  will  not  move  a  directory  from  one  file  system  to  another.  Use  cp(l)  instead. 
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NAME 

nawk  -  pattern  scanning  and  processing  language 
SYNOPSIS 

awk  [ -f program-file  ]  [  -F  c  ]  [ program  ]  [  variable  -value  . . .  ]  {filename,. . ] 

DESCRIPTION 

nawk  is  a  new  version  of  awk(l)  that  provides  additional  features  including,  dynamic  regular  expressions, 
additional  built-ins  and  operators,  and  user  defined  functions.  Other  implementations  refer  to  this  com¬ 
mand  by  its  original  name,  awk,  choosing  to  replace  the  original  program  with  the  enhanced  one.  Since 
there  is  a  slight  incompatibility  between  the  two  versions  (see  BUGS  below)  both  versions  am  available  in 
the  SunOS  environment,  the  original,  awk,  and  the  enhanced,  nawk. 

nawk  scans  each  mpni filename  for  lines  that  match  any  of  a  set  of  patterns  specified  in  program,  program 
string  must  be  enclosed  in  single  quotes  ( ’ )  to  protect  it  from  the  shell.  For  each  pattern  in  program  there 
may  be  an  associated  action  performed  when  a  line  of  a  filename  matches  the  pattern.  The  set  of  pattern- 
action  statements  may  appear  literally  as  program  or  in  a  file  specified  with  the  -f  program-file  option. 

OPTIONS 

-f  filename 

Specify  the  contents  of  filename  as  the  source  for  the  program. 

-F  c  Set  the  input  field  separator  to  c.  If  the  field  separator  is  longer  than  one  character,  it  is  taken  to 
be  a  regular  expression,  and  should  be  enclosed  in  single  quotes  to  protect  special  characters  from 
the  shell. 

variable =value 

Set  a  built-in  variable  to  value  before  the  first  record  of  the  next  filename  is  read.  See  Built-in 
Variables  below  for  a  complete  list  of  available  variables. 

USAGE 

Input  Lines 

Input  files  are  read  in  order;  if  there  are  no  files,  the  standard  input  is  read.  The  file  name  means  the 
standard  input  Each  input  line  is  matched  against  the  pattern  portion  of  every  pattern-action  statement;  the 
associated  action  is  performed  for  each  matched  pattern. 

An  input  line  is  normally  made  up  of  fields  separated  by  white  space.  This  default  can  be  changed  by  using 
the  FS  built-in  variable  or  the  ~F  c  option.)  The  fields  are  denoted  $1,  $2, . . . ;  $0  refers  to  the  entire  line. 

Pattern-action  Statements 

nawk  programs  contain  pattern-action  statements  of  the  form: 
pattern  [  action  } 

Either  pattern  or  action  may  be  omitted.  If  there  is  no  action  with  a  pattern,  the  matching  line  is  printed.  If 
there  is  no  pattern  with  an  action,  the  action  is  performed  on  every  input  line. 

Patterns  are  arbitrary  Boolean  combinations  (!,  1 1  ,  &&,  and  parentheses)  of  relational  expressions  and  reg¬ 
ular  expressions.  A  relational  expression  is  one  of  the  following: 

expression  relop  expression 
expression  matchop  regular  expression 
expression  in  array-name 
(expression,  expression, ...)  in  array-name 

where  relop  is  any  of  the  six  relational  operators  in  C,  and  matchop  is  either  “  (contains)  or  T  (does  not 
contain).  An  expression  is  an  arithmetic  expression,  a  relational  expression,  the  special  expression 

var  in  array, 

or  a  Boolean  combination  of  these. 
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The  special  patterns  BEGIN  and  END  may  be  used  to  capture  control  before  the  first  input  line  has  been 
read  and  after  the  last  input  line  has  been  read  respectively.  They  are  the  only  patterns  that  require  an 
action  statement.  These  keywords  do  not  combine  with  any  other  patterns. 

Regular  expressions  are  as  in  egrep  (see  grep(lV).  In  patterns  they  must  be  surrounded  by  slashes.  Iso¬ 
lated  regular  expressions  in  a  pattern  apply  to  the  entire  line.  Regular  expressions  may  also  occur  in  rela¬ 
tional  expressions.  A  pattern  may  consist  of  two  patterns  separated  by  a  comma;  in  this  case,  the  action  is 
performed  for  all  lines  between  an  occurrence  of  the  first  pattern  and  the  next  occurrence  of  the  second  pat¬ 
tern. 


An  action  is  a  sequence  of  statements.  A  statement  may  be  one  of  the  following: 

if  ( expression )  statement  [  else  statement  ] 

while  ( expression )  statement 

do  statement  while  ( expression ) 

for  ( expression  ;  expression  ;  expression )  statement 

for  ( var  in  array  )  statement 

delete  may[subscript] 

break 

continue 

(  [  statement  ] . . .  ) 

expression  #  commonly  variable  =  expression 

print  [  expression-list  ]  [  >expr€Ssion  ] 

printf format  [ ,  expression-list  ]  [  >expression  ] 

next  #  skip  remaining  patterns  on  this  input  line 

exit  [expr]  #  skip  the  rest  of  the  input;  exit  status  is  expr 

return  [expr] 

Statements  are  terminated  by  semicolons,  right  braces,  or  NEWLINE  characters.  An  empty  expression-list 
stands  for  the  whole  input  line.  Expressions  take  on  string  or  numeric  values  as  appropriate,  and  are  built 
using  the  operators  +,  ♦,  /,  %,  and  concatenation  (indicated  by  a  blank).  The  C  operators  ++,  — +=, 

-=,  +=,  /=,  and  %=  are  also  available  in  expressions.  Variables  may  be  scalars,  array  elements  (denoted 
jc[i]),  or  fields.  Variables  are  initialized  to  the  null  string  or  zero.  Array  subscripts  may  be  any  string,  not 
necessarily  numeric;  this  allows  for  a  form  of  associative  memory.  String  constants  are  quoted  ("). 

The  print  statement  prints  its  arguments  on  the  standard  output,  or  on  a  file  if  >expression  is  present,  or  on 
a  pipe  if  ‘|  emd'  is  present.  The  arguments  are  separated  by  the  current  output  field  separator  and  ter¬ 
minated  by  the  output  record  separator.  The  printf  statement  formats  its  expression  list  according  to  the 
format  (see  printf(3V)). 

Built-in  Variables 

A  regular  expression  may  be  used  to  separate  fields  by  using  the  -F  c  option  or  by  assigning  the  expres¬ 
sion  to  the  built-in  variable  FS.  The  default  is  to  ignore  leading  blanks  and  to  separate  fields  by  blanks 
and/or  tab  characters.  However,  if  FS  is  assigned  a  value,  leading  blanks  are  no  longer  ignored. 

Built-in  variables  include: 


ARGC 

ARGV 

HLENAME 

FNR 

FS 

NF 

NR 

OFMT 


Command  line  argument  count. 

Command  line  argument  array. 

Name  of  the  current  input  file. 

Ordinal  number  of  the  current  record  in  the  current  file. 
Input  field  separator  regular  expression  (default  blank). 
Number  of  fields  in  the  current  record. 

Ordinal  number  of  the  current  record. 

Output  format  for  numbers  (default  %.6g). 
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OPS  Output  field  separator  (default  blank). 

ORS  Output  record  separator  (default  NEWLINE) . 

RS  Input  record  separator  (default  NEWLINE) . 

SUBSEP  Separates  multiple  subscripts  (default  is  034). 

nawk  has  a  variety  of  built-in  functions:  arithmetic,  string,  input/output,  and  general. 

The  arithmetic  functions  are:  atan2^  cos^  exp,  int,  log,  rand,  sin,  sqrt,  and  srand.  int  truncates  its  argument 
to  an  integer,  rand  returns  a  random  number  between  0  and  1.  srand  ( expr )  sets  the  seed  value  for  rand 
to  expr  or  uses  the  time  of  day  if  expr  is  omitted. 

The  string  functions  are: 

gsub(/br,Vep/,‘m) 

behaves  like  sub  (see  below),  except  that  it  replaces  successive  occurrences  of  the  regu¬ 
lar  expression  (like  the  ed  global  substitute  command). 

returns  the  position  in  string  s  where  string  t  first  occurs,  or  0  if  it  does  not  occur  at  all. 
truncates  to  an  integer  value. 

returns  the  length  of  its  argument  taken  as  a  string,  or  of  the  whole  line  if  there  is  no 
argument. 

returns  the  position  in  string  s  where  the  regular  expression  re  occurs,  or  0  if  it  does  not 
occur  at  all.  RSTART  is  set  to  the  starting  position  (which  is  the  same  as  the  returned 
value),  and  RLENGTH  is  set  to  the  length  of  the  matched  string. 

random  number  on  (0, 1). 

splits  the  string  s  into  array  elements  fl[2],  a[n],  and  returns  n.  The  separation  is 
done  with  the  regular  expression  fs  or  with  the  field  separator  FS  if  fs  is  not  given. 

sets  the  seed  for  rand 


index(s,t) 

int 

length(s) 

niatch(s,‘re) 

rand 

split(5,‘fl,7y) 

srand 


expr 'expr, \ . .) 

formats  the  expressions  according  to  the  printf(3V)  format  given  by  fmt  and  returns  the 
resulting  string. 

mh(for,'repi,Hn)  substitutes  the  string  repl  in  place  of  the  first  instance  of  the  regular  expression  for  in 
string  in  and  returns  the  number  of  substitutions.  If  in  is  omitted,  nawk  substitutes  in  the 
current  record  ($0). 

substr(5,‘m,‘«)  returns  the  n -character  substring  of  s  that  begins  at  position  m.  The  input/output  and 
general  functions  are: 


close(filename) 
cmd  I  getline 

getline 
getline  <file 
getline  x 
getline  x  <file 

system(cmd) 


closes  the  file  or  pipe  named  filename. 

pipes  the  output  of  cmd  into  getline;  each  successive  call  to  getline  returns  the  next  line 
of  output  from  cmd. 

sets  $0  to  the  next  input  record  from  the  current  input  file. 

sets  $0  to  the  next  record  from  7/^. 

sets  variable  x  instead. 

sets  X  from  the  next  record  of  file. 

executes  cmd  and  returns  its  exit  status.  All  forms  of  getline  return  1  for  successful 
input,  0  for  end  of  file,  and  -1  for  an  error. 
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nawk  also  provides  user-defined  functions.  Such  functions  may  be  defined  (in  the  pattern  position  of  a 
pattern-action  statement)  as 

function  name{args,..^  (  stmts  } 
func  name{args [  stmts  ) 

Function  arguments  are  passed  by  value  if  scalar  and  by  reference  if  array  name.  Argument  names  are 
local  to  the  function;  all  other  variable  names  are  global.  Function  calls  may  be  nested  and  functions  may 
be  recursive.  The  return  statement  may  be  used  to  return  a  value. 

EXAMPLES 

Print  lines  longer  than  72  characters: 
length  >  72 

Print  first  two  fields  in  opposite  order: 

{  print  $2,  $1 } 

Same,  with  input  fields  separated  by  comma  and/or  blanks  and  tabs: 

BEGIN  {FS=",[\t]*l[\t]+"} 

{  print  $2,  $1 } 

Add  up  first  column,  print  sum  and  average: 

{s+=$l} 

END  {  print  "sum  is",  s,  "  average  is",  s/NR  } 

Print  fields  in  reverse  order: 

{  for  (i  =  NF;  i  >  0;  — i)  print  $i } 

Print  all  lines  between  start/stop  pairs: 

/start/,  /stop/ 

Print  all  lines  whose  first  field  is  different  fiom  previous  one: 

$1  !=  prev  {  print;  prev  =  $1 } 

Simulate  echo(lV): 

BEGIN  { 

for  (i  =  1;  i  <  ARGC;  i++) 

printf  "  %s",  ARGV(i] 
printf  "\n" 
exit 

} 

Print  file,  filling  in  page  numbers  starting  at  5: 

/Page/  {  $2  =  n++;  } 

{  print } 

example  %  nawk  -f  program  n=5  input 

SEE  ALSO 

grep(lV).  lex(l),  sed(l V),  printf(3V) 

Editing  Text  Files 

A.  V.  Aho,  B.  W.  Keminghan,  P.  J.  Weinberger,  The  AWK  Programming  Language  Addison-Wesley, 
1988. 
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BUGS 

Input  white  space  is  not  preserved  on  output  if  fields  are  involved. 

There  are  no  explicit  conversions  between  numbers  and  strings.  To  force  an  expression  to  be  treated  as  a 
number  add  0  to  it;  to  force  it  to  be  treated  as  a  string  concatenate  the  null  string  (”  ”)  to  it. 

Pattern-action  statements  must  be  separated  by  either  a  semi-colon  or  a  NEWLINE.  This  is  an  incompatibil¬ 
ity  with  the  old  version  of  awk. 
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NAME 

newgrp  -  log  in  to  a  new  group 
SYNOPSIS 

newgrp  [  -  ]  [  group  ] 

DESCRIPTION 

newgrp  changes  a  user’s  group  identification.  Only  the  group-ID  is  changed;  the  user  remains  a  member 
of  all  groups  previously  established  by  setgroups  (see  getgroups(2V)).  The  user  remains  logged  in  and 
the  current  directory  is  unchanged,  but  the  group-ID  of  newly-created  files  will  be  set  to  the  new  effective 
group-ID  (see  open(2V)).  The  user  is  always  given  a  new  shell,  replacing  the  current  shell,  regardless  of 
whether  newgrp  terminated  successfully  or  due  to  an  error  condition  (such  as  an  unknown  group). 

Exported  variables  retain  their  values  after  invoking  newgrp;  however,  all  unexported  variables  are  either 
reset  to  their  default  value  or  set  to  null.  System  variables  (such  as  HOME,  LOGNAME,  PATH,  SHELL, 
TERM,  and  USER),  unless  exported  by  the  system  or  explicitly  exported  by  the  user,  are  reset  to  default 
values.  Note;  the  shell  command  export  (see  sh(l))  is  the  method  to  export  variables,  while  the  C  shell 
command  setenv  (see  csh(l))  implicitly  exports  its  argument 

With  no  arguments,  newgrp  changes  the  group  identification  back  to  the  group  specified  in  the  user’s  pass¬ 
word  file  entry. 

If  the  first  argument  to  newgrp  is  a  the  environment  is  changed  to  what  would  be  expected  if  the  user 
actually  logged  in  again. 

A  password  is  demanded  if  the  group  has  a  password  and  the  user  does  not,  or  if  the  group  has  a  password 
and  the  user  is  not  listed  in  /etc/group  as  being  a  member  of  that  group. 

FILES 

/etc/group  system  group  file 

/etc/passwd  system  password  file 

SEE  ALSO 

csh(l),  login(l),  sh(l),  su(lV),  open(2V),  getgroups(2V),  initgroups(3),  environ(5V),  group(5), 
passwd(5) 

NOTES 

For  consistency  with  login  naming  rules  (which  do  not  allow  8-bit  file  names),  group  identifications  cannot 
contain  8-bit  characters.  See  login(l)  for  explanations  about  why  login  is  not  8-bit  clean. 

BUGS 

There  is  no  convenient  way  to  enter  a  password  into  /etc/group.  Use  of  group  passwords  is  not 
encouraged,  because,  by  their  very  nature,  they  encourage  poor  security  practices.  Group  passwords  may 
disappear  in  the  future. 
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NAME 

nice  -  run  a  command  at  low  priority 
SYNOPSIS 

nice  [  -number  ]  command  [  arguments  ] 

DESCRIPTION 

There  are  two  distinct  versions  of  nice:  it  is  built  in  to  the  C  shell,  and  is  an  executable  program  available 
in  /usr/bin/nice  for  use  with  the  Bourne  shell. 

nice  executes  command  with  the  “nice”  value  number.  The  nice  value  is  one  of  the  factors  used  by  the 
kernel  to  determine  a  process’s  scheduling  priority.  Scheduling  priorities  range  from  0  to  127.  The  higher 
the  value,  the  lower  the  command’s  scheduling  priority,  and  the  lower  the  value,  the  higher  the  command’s 
scheduling  priority.  In  addition  to  the  nice  value,  the  kernel  also  recent  CPU  usage  by  the  process,  the  time 
the  process  has  been  waiting  to  run,  and  other  factors  to  arrive  at  scheduling  priority. 

If  the  number  argument  is  present,  the  nice  value  is  incremented  or  decremented  by  that  amount,  between 
the  limits  -20  and  19.  If  there  is  no  number  argument,  the  default  nice  value  is  10  for  the  Bourne  shell,  and 
4  for  the  C-shell. 

The  super-user  may  run  commands  with  priority  higher  than  normal  by  using  negative  nice  values  such  as 
-10. 

EXAMPLES 

The  following  examples  illustrate  the  use  of  nice  values  for  users  (not  the  super-user)  using  /usr/bin/nice. 
The  examples  use  the  -I  option  to  ps(l)  because  it  shows  both  the  nice  value  and  the  kernel  scheduling 
priority.  Notice  the  NI  and  PRI  columns.  In  the  first  example,  the  user  doesn’t  use  nice,  so  the  niceness  is 
zero,  the  default  value,  which  is  reflected  by  0  in  the  NI  column.  The  corresponding  process  scheduling 
priority  is  shown  in  the  PRI  column  as  28  (this  may  vary  because  of  the  other  factors  the  kernel’s  scheduler 
uses). 

In  the  second  example,  the  user  uses  a  nice  value  of  10,  and  the  corresponding  priority  is  53,  a  higher 
numerical  value  but  a  lower  priority.  Notice  that  this  is  the  same  as: 

example%  nice  ps  -I 

because  the  default  nice  value  is  10. 

In  the  third  example,  the  user  asks  that  the  nice  value  be  incremented  by  20,  but  it’s  shown  as  19  under  NI, 
because  that’s  the  upper  limit  of  niceness. 

A  fourth  example  shows  the  error  message  when  an  ordinary  user  tries  to  decrement  the  nice  value. 
exaniple%  ps~l 

FUID  PID  PPID  CP  PRI  NI  SZ  RSS  WCHAN  ST  AT  TT  TIME  COMMAND 
19442  16623  9725 12  28  0  120  336  R  p2  0:00ps-l 
example  %  nice -10  ps -I 

FUID  PID  PPID  CP  PRI  NI  SZ  RSS  WCHAN  ST  AT  TT  TIME  COMMAND 
19442  16608  16606  32  53 10  120  328  R  N  p2  0:00  ps  -I 
example%  nice  -20  ps  -I 

F  UID  PID  PPID  CP  PRI  NI  SZ  RSS  WCHAN  STAT  TT  TIME  COMMAND 
19442  16609  16606  37  72  19  120  328  R  N  p2  0:00  ps  -I 
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example%  nice — 20ps-l 
nice:  setpriority:  Permission  denied 
example  % 

SEE  ALSO 

csh(l),  getpriority(2),  nice(3V),  pstat(8),  renice(8) 

DIAGNOSTICS 

nice  reiums  the  exit  status  of  the  subject  command. 

BUGS 

The  nice  command  has  a  different  syntax  than  the  /usr/bin/nice  command  described  here.  It  uses  the  plus 
sign,  +,  to  increment  nice  values,  for  example: 

example  %  nice  +number 

increments  the  nice  value  by  number.  It  uses  a  single  a  minus  sign,  to  decrement  nice  values  for  super- 
user. 


w 
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NAME 

nl  -  line  numbering  filter 
SYNOPSIS 

nl  [  -p  ]  [  -htype  ]  [  -btype  ]  [  -ftype  ]  [  -ystan  ]  [  -uncr  ]  [  ~\num  ]  [  ~ssep  ]  [  -wwidth  ] 

[  -nfmt  ]  [  -ddelim  ]  filename 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

nl  reads  lines  from  filename  (or  the  standard  input),  numbers  them  according  to  the  options  in  effect,  and 
sends  its  output  to  the  standard  output. 

nl  views  the  text  it  reads  in  terms  of  logical  pages.  Line  numbering  is  normally  reset  at  the  start  of  each 
page,  A  logical  page  is  composed  of  header,  body  and  footer  sections.  The  start  of  each  page  section  is 
signaled  by  input  lines  containing  section  delimiters  only: 

Start  of  file 


header 

body 

\: 

footer 

Empty  sections  are  valid.  Different  line-numbering  options  are  available  within  each  section.  The  default 
scheme  is  no  numbering  for  headers  and  footers. 

OPTIONS 

-p  Do  not  restart  numbering  at  logical  page  delimiters. 

-btype  Specify  which  logical  page  body  lines  are  to  be  numbered,  type  is  one  of: 
a  number  all  lines 

t  number  lines  with  printable  text  only  (the  default) 
n  no  line  numbering 

p  rexp  number  only  lines  that  contain  the  regular  expression  rexp 

-btype  Same  as  -btype  except  for  the  header.  The  default  type  for  the  logical  page  header  is  n  (no 
lines  numbered). 

-ftype  Same  as  -btype  except  for  the  footer.  The  default  for  logical  page  footer  is  n  (no  lines  num¬ 
bered). 

-y start  start  is  the  initial  value  used  to  number  logical  page  lines.  The  default  is  1. 

-Uncr  incr  is  the  increment  by  which  to  number  logical  page  lines.  The  default  is  1. 

-ssep  sep  is  the  character(s)  used  to  separate  the  line  number  from  the  corresponding  text  line.  The 
default  is  a  TAB. 

-ymidth  width  is  the  number  of  characters  to  be  used  for  the  line-number  field.  The  default  is  6. 

-nfmt  fmt  is  the  line  numbering  format.  Recognized  values  are: 

rn  right  justified,  leading  zeroes  suppressed  (the  default) 

In  left  justified,  leading  zeroes  suppressed 

rz  right  justified,  leading  zeroes  kept 
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~\num  num  is  the  number  of  blank  lines  to  be  considered  as  one.  For  example,  -12  results  in  only  the 
second  adjacent  blank  being  numbered  (if  the  appropriate  -ha,  -ba,  and/or  -fa  option  is  set). 
The  default  is  1. 

-6xx  The  delimiter  characters  specifying  the  start  of  a  logical  page  section  may  be  changed  from 

the  default  characters  (V)  to  two  user-specified  characters.  If  only  one  character  is  entered, 
the  second  character  remains  the  default  character  (:).  No  space  should  appear  between  the 
-d  and  the  delimiter  charactks.  To  enter  a  backslash,  use  two  backslashes. 

EXAMPLE 

The  command: 

nl  -vlO  -ilO  -d!+ filename! 

will  number  filename!  starting  at  line  number  10  with  an  increment  of  ten.  The  logical  page  delimiters  are 

!+. 

SEE  ALSO 

pr(lV) 
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NAME 

nm  -  print  symbol  name  list 
SYNOPSIS 

nm  [  -gnoprsua  ]  [  [filename  ] . , . 

DESCRIPTION 

nm  prints  the  name  list  (symbol  table)  of  each  object  filename  in  the  argument  list.  If  an  argument  is  an 
archive,  a  listing  for  each  object  file  in  the  archive  will  be  produced.  If  no  filename  is  given,  the  symbols  in 
a.out  are  listed. 

Output  Format 

Each  symbol  name  is  preceded  by  its  value  (blanks  if  undefined)  and  one  of  the  letters: 

A  absolute 

B  bss  segment  symbol 

C  common  symbol 

D  data  segment  symbol 

f  filename 

t  a  static  function  symbol 

T  text  segment  symbol 

U  undefined 

-  debug,  giving  symbol  table  entries  (see  -a  below) 

The  type  letter  is  upper  case  if  the  symbol  is  external,  and  lower  case  if  it  is  local.  The  output  is  sorted 
alphabetically. 

OPTIONS 

-a  Print  all  symbols. 

-g  Print  only  global  (external)  symbols. 

-n  Sort  numerically  rather  than  alphabetically. 

-o  Prepend  file  or  archive  element  name  to  each  output  line  rather  than  only  once. 

-p  Do  not  sort;  print  in  symbol-table  order. 

-r  Sort  in  reverse  order. 

-s  Sort  according  to  the  size  of  the  external  symbol  (computed  from  the  difference  between  the  value 

of  the  symbol  and  the  value  of  the  symbol  with  the  next  higher  value).  This  difference  is  the  value 
printed. 

“U  Print  only  undefined  symbols. 

EXAMPLE 

example  %  nm 

prints  the  symbol  list  of  the  file  named  a.out,  the  default  output  file  for  the  C,  compiler. 

SEE  ALSO 

ar(lV),  as(l),  cc(lV),  ld(l),  tmpnam(3S),  a.out(5),  ar(5),  coff(5) 

BUGS 

To  see  what  is  in  a  shared  library,  run  nm  on  the  static  (.a)  version. 

Sun386i  BUGS 

When  all  the  symbols  are  printed,  they  must  be  printed  in  the  order  they  appear  in  the  symbol  table  in  order 
to  preserve  scoping  information.  Therefore,  the  -v  and  -n  options  should  be  used  only  in  conjunction  with 
the  -e  option. 
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NAME 

nohup  -  run  a  command  immune  to  hangups  and  quits 
SYNOPSIS 

/usr/bin/nohup  command  [  arguments  ] 

SYSTEM  V  SYNOPSIS 

/usr/5bin/nohup  command  [  arguments  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4,1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

There  are  three  distinct  versions  of  nohup:  it  is  built  in  to  the  C  shell,  and  is  an  executable  program  avail¬ 
able  in  /usr/bin/nohup  and  /usr/5bin/nohup  when  using  the  Bourne  shell. 

The  Bourne  shell  version  of  nohup  executes  command  such  that  it  is  immune  to  HUP  (hangup)  and  TERM 
(terminate)  signals.  If  the  standard  output  is  a  terminal,  it  is  redirected  to  the  file  nohup.out.  The  standard 
error  is  redirected  to  follow  the  standard  output. 

The  priority  is  incremented  by  5.  nohup  should  be  invoked  from  the  shell  with  ‘&’  in  order  to  prevent  it 
from  responding  to  interrupts  or  input  from  the  next  user. 

SYSTEM  V  DESCRIPTON 

Processes  run  by  nohup  are  immune  to  HUP  (hangup)  and  QUIT  (quit)  signals;  nohup  does  not  arrange  to 
make  them  immune  to  a  TERM  (terminate)  signal,  so  unless  they  arrange  to  be  immune  to  a  TERM  signal, 
or  the  shell  makes  them  immune  to  a  TERM  signal,  they  will  receive  that  signal.  If  nohup.out  is  not  writ¬ 
able  in  the  current  directory,  output  is  redirected  to  $HOME/nohup.out.  If  the  standard  error  is  a  terminal, 
it  is  redirected  to  the  standard  output,  otherwise  it  is  not  redirected.  The  priority  of  the  process  run  by 
nohup  is  not  altered. 

EXAMPLE 

ft  is  frequently  desirable  to  apply  nohup  to  pipelines  or  lists  of  commands.  This  can  be  done  only  by  plac¬ 
ing  pipelines  and  command  lists  in  a  single  file,  called  a  shell  script.  The  command 

example  %  nohup  sh  script 

applies  to  everything  in  script.  (If  the  script  is  to  be  executed  often,  then  the  need  to  type  sh  can  be  elim¬ 
inated  by  giving  script  execute  permission).  Add  an  ampersand  and  the  contents  of  script  are  run  in  the 
background  with  interrupts  also  ignored  (see  sh(l)): 

example  %  nohup  script  & 

FILES 

nohup.out 

$HOME/nohup.out 

SEE  ALSO 

chmod(lV),  csh(l),  nice(l),  sh(l),  signal(3V) 

BUGS 

If  you  use  csh(l),  then  commands  executed  with  *&’  are  automatically  immune  to  HUP  signals  while  in  the 
background. 

There  is  a  C  shell  built-in  command  nohup  that  provides  immunity  from  terminate,  but  does  not  redirect 
ouq)ut  to  nohup.out. 
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nohup  does  not  recognize  command  sequences.  For  instance, 
nohup  commandl ;  command! 
applies  only  to  commandl  and  the  command: 

nohup  (commandl ;  command!) 
is  syntactically  incorrect. 

Be  careful  of  where  the  standard  error  is  redirected.  The  following  command  may  put  error  messages  on 
tape,  making  it  unreadable: 

nohup  cpio  -o  <  list  >  /dev/miit/lni& 

while 

nohup  cpio  -o  <  list  >  /dev/rmt/lm  2>errors& 
puts  the  error  messages  into  the  file  errors. 
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NAME 

nroff  -  format  documents  for  display  or  line-printer 
SYNOPSIS 

nroff  [  -ehig  ]  [  -mname  ]  [  -nN  ]  [  -opagelist  ]  [  -toN  ]  [  -sN  ]  [  -Tname  ] 


AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4J  for 
information  on  how  to  install  optional  software, 

DESCRIPTION 

nroff  formats  text  in  the  named  files  for  typewriter-like  devices.  See  also  troff(l).  The  full  capabilities  of 
nroff  and  troff  are  described  in  Formatting  Documents. 

If  no  file  argument  is  present,  nroff  reads  the  standard  input.  An  argument  consisting  of  a  ’  is  taken  to  be 
a  file  name  corresponding  to  the  standard  input. 

OPTIONS 

Options  may  appear  in  any  order  so  long  as  they  appear  before  the  files. 

-e  Produce  equally-spaced  words  in  adjusted  lines,  using  full  terminal  resolution. 

-h  Use  output  TAB  characters  during  horizontal  spacing  to  speed  output  and  reduce  output  character 
count.  TAB  settings  are  assumed  to  be  every  8  nominal  character  widths. 

-i  Read  the  standard  input  after  the  input  files  are  exhausted. 

~q  Invoke  the  simultaneous  input-output  mode  of  the  rd  request. 

—saname 

Prepend  the  macro  file  /usr/share/lib/tmac/tmac.name  to  the  input  files. 

-nN  Number  first  generated  page  N. 

-opagelist 

Print  only  pages  whose  page  numbers  appear  in  the  comma-separated  list  of  numbers  and  ranges. 
A  range  N~M  means  pages  N  through  M ;  an  initial  -N  means  from  the  beginning  to  page  N;  and  a 
final  N~  means  from  N  to  the  end. 

-toN  Set  register  a  (one-character)  to  N. 

-sN  Stop  every  N  pages,  nroff  will  halt  prior  to  every  N  pages  (default  N=l)  to  allow  paper  loading  or 
changing,  and  will  resume  upon  receipt  of  a  NEWLINE. 

-Tname 

Prepare  output  for  a  device  of  the  specified  name.  Known  names  are: 


37 

crt  I  Ipr  I  tn300 

300 

300-12 

300S  I  302  I  dtc 
300S-12  I  302-12 

382 

382-12 

450  I  ipsi 

450-12  I  ipsil2 

450-12-8 

450X 

832 


Teletype  Corporation  Model  37  terminal  —  this  is  the  default. 

GE  TermiNet  300,  or  any  line  printer  or  terminal  without  half-line  capa¬ 
bility, 

DASI-300. 

DASI-300— 12-pitch. 

DASI-300S. 

dtcl2 

DASI-300S. 

DASI-382  (fancy  DTC  382). 

DASI-82  (fancy  DTC  382  —  12-pitch). 

DASI-450  (Diablo  Hyterm). 

DASI-450  (Diablo  Hyterm)  —  12-pitch. 

DASI-450  (Diablo  Hyterm)  —  12-pitch  and  lines-per-inch. 

DASI-450X  (Diablo  Hyterm). 

AJ  832. 
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833 

AJ833. 

832-12 

AJ  832— 12-pitch. 

833-12 

AJ  833  —  12-pitch. 

epson 

Epson  FX80. 

itoh 

C:ITOH  Prowriter. 

itoh-12 

C:ITOH  Prowriter  —  12-pitch. 

nec 

NEC  55?0  or  NEC  77?0  Spinwriter. 

necl2 

NEC  55?0  or  NEC  77?0  Spinwriter  —  12-pitch. 

nec-t 

NEC  55?0/77?0  Spinwriter  —  Tech-Math/Times-Romanthimble. 

qume 

Qume  Sprint  —  5  or9. 

qumel2 

Qume  Sprint  —  5  or  9,12-pitch. 

xerox 

Xerox  17?0  or  Diablo  16?0. 

xeroxl2 

Xerox  1770  or  Diablo  1670  —  12-pitch. 

x-ecs 

Xerox/Diablo  1730/630  —  Extended  Character  Set. 

x-ecsl2 

Xerox/Diablo  1730/630  —  Extended  Character  Set,  12-pitch. 

man 

Dumb  terminal,  used  for  online  man  pages. 

EXAMPLE 

The  following  command: 

example%  nroff  -s4 

-me  users.guide 

formats  users.guide  using  the  - 

-me  macro  package,  and  stopping  every  4  pages. 

FILES 

/tmp/ta* 

temporary  file 

/usr/sbare/lib/tmac/tmac.* 

standard  macro  files 

/  usr/sbare/lib/term/* 

terminal  driving  tables  for  nroff 

/usr/sbare/lib/term/README 

index  to  terminal  description  files 

SEE  ALSO 

cbecknr(l),  coI(lV),  eqn(l),  tbl(l),  troff(l),  term(5),  man(7),  me(7),  ms(7) 

Formatting  Documents 

NOTES 

nroff  is  not  8-bit  clean  because  making  nroff  8-bit  clean  would  require  rewriting  the  nroff  internals  and 

filters.  Also,  some  nroff  syntax  is  based  on  ASCII  only  and  does  not  lend  itself  to  8-bit  character 

sequences. 
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NAME 

objdump  -  dump  selected  parts  of  a  COFF  object  file 
SYNOPSIS 

objdump  [  option  [  modifier . . ,  ]  ]  filename  . . . 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 


DESCRIPTION 

The  objdump  command  dumps  selected  parts  of  each  of  its  object  filename  arguments.  This  command  is 
compatible  with  System  V  in  all  its  options.  It  will  accept  both  object  files  and  archives  of  object  files. 

objdump  command  attempts  to  format  the  information  it  dumps  in  a  meaningful  way,  printing  certain 
information  in  character,  hex,  octal  or  decimal  representation  as  appropriate. 

OPTIONS 

-a  Dump  the  archive  header  of  each  member  of  each  archive  file  argument. 

-g  Dump  the  global  symbols  in  the  symbol  table  of  an  archive. 

-f  Dump  each  file  header. 

-0  Dump  each  optional  header. 

-h  Dump  section  headers. 

-s  Dump  section  contents. 

-r  Dump  relocation  information. 

“1  Dump  line  number  information. 

-t  Dump  symbol  table  entries. 

-z  name  Dump  line  number  entries  for  the  named  function. 

~c  Dump  the  string  table. 

“L  Interpret  and  print  the  contents  of  the  Jib  sections. 


Modifiers 

The  following  modifiers  are  used  in  conjunction  with  the  options  listed  above. 

-d  number  Dump  the  section  number,  number,  or  the  range  of  sections  starting  at  number  and  ending  at 
the  number  specified  by  +d. 

+d  number  Dump  sections  in  the  range  either  beginning  with  first  section  or  beginning  with  section 
specified  by  -d. 

~n  name  Dump  information  pertaining  only  to  the  named  entity.  This  modifier  applies  to  -h,  -s,  -r,  -I, 
and  -t. 


-P 

-t  index 
+t  index 

-u 

-V 


Suppress  printing  of  the  headers. 

Dump  only  the  indexed  symbol  table  entry.  The  -t  used  in  conjunction  with  +t,  specifies  a 
range  of  symbol  table  entries. 

Dump  the  symbol  table  entries  in  the  range  ending  with  the  indexed  entry.  The  range  begins  at 
the  first  symbol  table  entry  or  at  the  entry  specified  by  the  -t  option. 

Underline  the  name  of  the  file  for  emphasis. 

Dump  information  in  symbolic  representation  rather  than  numeric  (e.g.,  C_STATIC  instead  of 
0X02).  This  modifier  can  be  used  with  all  the  above  options  except  -s  and  -o. 
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~z  name  f  number 
-z  name  number 

Dump  line  number  entry  or  range  of  line  numbers  starting  at  number  for  the  named  function. 

+z  number  Dump  line  numbers  starting  at  either  function  name  or  number  specified  by  -z,  up  to  number 
specified  by  +z. 

White  space  separating  an  option  and  its  modifier  is  optional. 

SEE  ALSO 

ar(5).coff(5) 
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NAME 

od  -  octal,  decimal,  hexadecimal,  and  ascii  dump 
SYNOPSIS 

od  [  -format  ]  [filename  ]  [  [+]ojfset[.]  [b]  [label]  ] 

SYSTEM  V  SYNOPSIS 

/usr/5bin/od  [arguments] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

od  displays  ^/eno/ne,  or  its  standard  input,  in  one  or  more  dump  formats  as  selected  by  the  first  argument. 
If  the  first  argument  is  missing,  -o  (octal)  is  the  default.  Dumping  continues  until  an  EOF. 

Format  Arguments 

The  meanings  of  the  format  argument  characters  are: 

a  Interpret  bytes  as  characters  and  display  them  with  their  ASCII  names.  If  the  p  character  is  given 
also,  bytes  with  even  parity  are  underlined.  If  the  P  character  is  given,  bytes  with  odd  parity  are 
underlined.  Otherwise  the  parity  bit  is  ignored. 

b  Interpret  bytes  as  unsigned  octal. 

c  Interpret  bytes  as  ASCII  characters.  Certain  non-graphic  characters  appear  as  C  escapes:  NUL=\0, 
BACKSPACE=\b,  FORMFEED=\f,  NEWLINE=\n,  RETURN=\r,  TAB=\t;  others  appear  as  3-digit  octal 
numbers.  Bytes  with  the  parity  bit  set  are  displayed  in  octal. 

d  Interpret  (short)  words  as  unsigned  decimal. 

f  Interpret  long  words  as  floating  point. 

h  Interpret  (short)  words  as  unsigned  hexadecimal. 

i  Interpret  (short)  words  as  signed  decimal. 

1  Interpret  long  words  as  signed  decimal. 

o  Interpret  (short)  words  as  unsigned  octal. 

s[rt]  Look  for  strings  of  ASCII  graphic  characters,  terminated  with  a  null  byte,  n  specifies  the  minimum 
length  string  to  be  recognized.  By  default,  the  minimum  length  is  3  characters. 

V  Show  all  data.  By  default,  display  lines  that  are  identical  to  the  last  line  shown  are  not  output,  but  are 
indicated  with  an  in  column  1. 

w[n]  Specifies  the  number  of  input  bytes  to  be  interpreted  and  displayed  on  each  output  line.  If  w  is  not 
specified,  16  bytes  are  read  for  each  display  line.  If  n  is  not  specified,  it  defaults  to  32. 

X  Interpret  (short)  words  as  hexadecimal. 

An  upper  case  format  character  implies  the  long  or  double  precision  form  of  the  object. 

The  offset  argument  specifies  the  byte  offset  into  the  file  where  dumping  is  to  commence.  By  default  this 
argument  is  interpreted  in  octal.  A  different  radix  can  be  specified;  if  is  appended  to  the  argument,  then 
offset  is  interpreted  in  decimal.  If  offset  begins  with  x  or  Ox,  it  is  interpreted  in  hexadecimal.  If  b  (B)  is 
appended,  the  offset  is  interpreted  as  a  block  count,  where  a  block  is  512  (1024)  bytes.  If  the  filename 
argument  is  omitted,  the  offset  argument  must  be  preceded  by  *+’. 

The  radix  of  the  displayed  address  will  be  the  same  as  the  radix  of  the  offsety  if  specified;  otherwise  it  will 
be  octal. 

label  will  be  interpreted  as  a  pseudo-address  for  the  first  byte  displayed.  It  will  be  shown  in  ()  following 
the  file  offset.  It  is  intended  to  be  used  with  core  images  to  indicate  the  real  memory  address.  The  syntax 
for  label  is  identical  to  that  for  offset. 
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SYSTEM  V  DESCRIPTION 

The  s  format  interprets  (short)  words  as  signed  decimal,  rather  than  searching  for  strings;  the  S  format 
searches  for  strings. 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  od.  On  entry  to  od,  these  environment  variables  are  checked  in  the  following  order: 
LC^CTYPE,  LANG,  and  LC_defauIt.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC__CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.1  “C”  locale. 

SEE  ALSO 

adb(l),  dbx(l),  dbxtool(l),  locale(5),  iso_8859_l(7) 

BUGS 

A  file  name  argument  cannot  start  with  *+’.  A  hexadecimal  offset  cannot  be  a  block  count.  Only  one  file 
name  argument  can  be  given. 

It  is  an  historical  botch  to  require  specification  of  object,  radix,  and  sign  representation  in  a  single  character 
argument. 
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NAME 

old-compact,  old-uncompact,  old-ccat-  compress  and  uncompress  files,  and  cat  them 
SYNOPSIS 

/usr/old/compact  [filename. . .  ] 
uncompact  [filename ...  ] 
ccat  [filename . . .  ] 

DESCRIPTION 

Note:  This  program  is  considered  to  be  obsolete,  and  will  not  be  distributed  or  supported  in  future  Sun 
releases. 

compact  compresses  the  named  files  using  an  adaptive  Huffman  code.  If  no  file  names  are  given,  the  stan¬ 
dard  input  is  compacted  to  the  standard  ouh}ut  compact  operates  as  an  on-line  algorithm.  Each  time  a 
byte  is  read,  it  is  encoded  immediately  according  to  the  current  prefix  code.  This  code  is  an  optimal  Huff¬ 
man  code  for  the  set  of  frequencies  seen  so  far.  It  is  unnecessary  to  prepend  a  decoding  tree  to  the 
compressed  file  since  the  encoder  and  the  decoder  start  in  the  same  state  and  stay  synchronized.  Further¬ 
more,  compact  and  uncompact  can  operate  as  filters.  In  particular: 

...  I  compact  I  uncompact  | . . . 

operates  as  a  (very  slow)  no-op. 

When  an  argument  file  is  given,  it  is  compacted  and  the  resulting  file  is  placed  in  file.C;  file  is  removed. 
The  first  two  bytes  of  the  compacted  file  code  the  fact  that  the  file  is  compacted.  This  code  is  used  to 
prohibit  recompaction. 

The  amount  of  compression  to  be  expected  depends  on  the  type  of  file  being  compressed.  Typical  values 
of  compression  are:  Text  (38%),  Pascal  Source  (43%),  C  Source  (36%)  and  Binary  (19%).  These  values 
are  the  percentages  of  file  bytes  reduced. 

uncompact  restores  the  original  file  from  a  file  called  file.C  which  was  compressed  by  compact.  If  no  file 
names  are  given,  the  standard  input  is  uncompacted  to  the  standard  output. 

ccat  cats  the  original  file  from  a  file  compressed  by  compact,  without  uncompressing  the  file. 

FILES 

*.C  compacted  file  created  by  compact,  removed  by  uncompact 

SEE  ALSO 

Gallager,  Robert  G.,  Variations  on  a  Theme  of  Huffman,  I.E.E.E.  Transactions  on  Information  Theory,  vol. 
IT-24,  no.  6,  November  1978,  pp.  668  -  674. 
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NAME 

old-eyacc  -  modified  yacc  allowing  much  improved  error  recovery 
SYNOPSIS 

/usr/old/eyacc  [  -v  ]  [  grammar  ] 

DESCRIPTION 

eyacc  is  a  version  of  yacc(l),  that  produces  tables  used  by  the  Pascal  system  and  its  error  recovery  rou¬ 
tines.  eyacc  fully  enumerates  test  actions  in  its  parser  when  an  error  token  is  in  the  look-ahead  set  This 
prevents  the  parser  from  making  undesirable  reductions  when  an  error  occurs  before  the  error  is  detected. 
The  table  format  is  different  in  eyacc  than  it  was  in  the  old  yacc,  as  minor  changes  had  been  made  for 
efficiency  reasons. 

SEE  ALSO 

yacc(l) 

Practical  LR  Error  Recovery  by  Susan  L.  Graham,  Charles  B.  Haley  and  W,  N,  Joy;  SIGPLAN  Conference 
on  Compiler  Construction,  August  1979. 

BUGS 

pc  and  its  error  recovery  routines  should  be  made  into  a  library  of  routines  for  the  new  yacc. 
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NAME 

old-filemerge  -  window-based  file  comparison  and  merging  program 
SYNOPSIS 

/usr/old/rnemerge  [  -br  ]  [  -a  ancestor  ]  [  -I  listfile  ]  [  leflfile  [  rightfile  [  outfile  ]  ]  ] 

DESCRIPTION 

Note:  This  program  is  considered  to  be  obsolete,  and  will  not  be  distributed  or  supported  in  future  Sun 
releases. 

filemerge  is  a  window-based  version  of  diff(l),  for  comparing  and  merging  text  files.  It  displays  two  files 
for  side-by-side  comparison,  each  in  a  read-only  text-subwindow.  Beneath  them,  an  editing  subwindow 
can  be  used  to  construct  a  merged  version — one  which  contains  selected  lines  from  either  or  both  input 
files,  along  with  any  additional  edits  you  may  make. 

leftfile  and  rightfile  are  the  files  to  be  compared,  and  outfile  is  name  of  the  file  containing  the  merged  ver¬ 
sion.  If  outfile  is  a  directory,  then  the  output  is  placed  in  the  file  outfile  (leftfile.  If  outfile  is  omitted,  the 
output  file  is  named  filemerge.  out  by  default.  If  no  filename  arguments  are  given,  you  can  enter  them 
from  within  the  tool  itself. 

OPTIONS 

-b  Ignore  leading  blanks  in  comparisons. 

-r  Read-only  mode.  Do  not  display  the  editing  subwindow. 

-a  ancestor 

Compare  both  files  with  respect  to  ancestor.  A  minus-sign  indicates  lines  that  have  been  deleted 
relative  to  the  ancestor.  A  plus-sign  indicates  lines  added  relative  to  the  ancestor. 

-I  listfile 

Process  a  list  of  filename  pairs.  With  this  option,  leftfile  and  rightfile  are  the  names  of  directories, 
and  listfile  contains  a  list  of  filenames  that  appear  in  both,  filemerge  compares  the  versions  of 
each  file  between  the  two  directories,  and  allows  you  to  create  a  merged  version  (typically  in  the 
directory  outfile).  The  SHIFT-Load  command  button,  which  is  selected  by  holding  the  SHIFT  key 
while  clicking  on  the  Load  button,  reads  in  the  next  pair  named  in  the  list.  If  listfile  is  then  the 
list  of  files  is  read  from  the  standard  input. 

USAGE 

The  text  in  the  editing  subwindow  (outfile)  is  initially  the  same  as  that  in  leftfile.  To  construct  a  merged 
version,  you  can  directly  edit  the  text  of  outfile  with  textedit  commands,  or  you  can  change  a  selected 
difference  to  match  rightfile  (the  one  on  the  right)  by  clicking  the  Right  button  in  the  top  panel. 

Differences 

At  any  given  time,  one  of  the  displayed  “differences”  is  current.  The  current  difference  is  indicated  by 
emboldening  the  symbol  adjacent  to  each  line,  and  also  by  the  notation  “i  of  n”  displayed  in  the  control 
panel.  Once  a  difference  is  current,  you  can  use  the  Left  and  Right  buttons  to  apply  either  the  left-hand  or 
the  right-hand  version  of  the  text  to  outfile.  The  Next  and  Prev  buttons  select  the  next  or  previous  differ¬ 
ence,  respectively. 

Property  Sheet 

You  can  customize  filemerge  using  the  property  sheet  to  set  or  alter  various  display  and  control  options. 
To  bring  up  the  property  sheet,  press  the  Props  function  key  (typically  L3)  while  the  mouse  is  over  any 
part  of  the  filemerge  window. 

Menus 

There  are  pop-up  menus  associated  with  several  of  the  control  panel  items,  and  a  menu  associated  with  the 
editing  subwindow.  The  former  provide  to  select  any  command  function  obtained  with  a  modified  mouse- 
button  (such  as  SHIFT-Next );  the  editing  subwindow’s  menu  has  items  that  control  the  filename  and  direc¬ 
tory  location  of  the  merged  output.  To  bring  up  a  menu,  move  the  mouse-cursor  to  the  command  button,  or 
to  the  editing  subwindow,  and  hold  down  the  RIGHT  mouse-button.  Select  a  desired  menu  item  by  releas¬ 
ing  the  mouse-button  after  moving  the  cursor  on  top  of  it. 
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Command  Buttons 

Next  Make  the  next  difference  current.  The  subwindow  scrolls,  if  necessary,  to  display  it. 

SHIFT-Next  12  Make  the  first  difference  current.  (Also  a  menu  item  from  the  Next  menu.) 

Prev  Make  the  previous  difference  current. 

SHIFT-Prev  12  Make  the  last  difference  current.  (Also  a  menu  item  from  the  Prev  menu.) 

Right  Apply  right-hand  version  of  the  current  difference  to  outfile.  If  autoadvance  is  in  effect, 

advance  to  the  next  difference. 

SHIFT-Right  12  Apply  the  right-hand  version  and  advance  to  the  next  difference,  unless 
autoadvance  is  in  effect.  (Also  a  menu  item  from  the  Right  menu.) 

CTRL-Right  Apply  the  right-hand  version  for  the  current  difference,  and  for  all  subsequent  differences 
up  to  the  end  of  the  file. 

Left  Apply  the  left-hand  version  of  the  current  difference. 

Undo  Undo  the  last  Right  or  Left  operation.  You  can  Undo  up  to  100  stacked  operations.  You 

cannot  undo  an  Undo. 


SHIFT-Undo  12  Undo  all  the  operations  since  the  last  Load,  or  the  last  100  operations. 

Scroll-Lock  When  in  effect,  the  three  text-subwindows  scroll  in  unison.  Otherwise  each  subwindow 
scrolls  independently. 

i  of  n  The  number  of  the  current  difference,  i ,  out  of  n  detected  differences.  Popping  up  a  menu 

on  this  item  allows  you  to  jump  to  a  selected  difference. 

Load  Load  the  files  whose  names  appear  by  the  prompts  Filel:  and  File2: . 

SHIFT-Load  12  When  the  -1  option  is  used,  load  the  files  from  the  directories  shown  in 
Filel  and  File2  corresponding  to  the  next  name  in  the  list  (taken  from  the  listfile  argument). 

Done  Save  outfile  and  close  the  tool.  The  name  used  to  save  the  file  appears  in  the  namestripe,  in 

the  same  fashion  as  textedit(l). 

SHIFT-Done  12  Save  without  closing.  You  can  also  save  the  merged  version  using  the  Save 
item  in  the  editing  subwindow’s  menu. 

Quit  Exit  the  tool.  You  must  explicitly  save  your  merged  outfile,  either  with  the  Done  button  or 

the  Save  item  in  the  editing  subwindow’s  menu. 

Properties 

Hitting  the  L3  function  key  brings  up  a  property  sheet  that  controls  several  filemerge  parameters.  The 
information  in  the  property  sheet  is  stored  in  the  file  7.  filemergerc.  The  property  panel  items  have  the  fol¬ 
lowing  meanings: 


Apply 

Reset 

Done 

autoadvance 

Toplines 

Bottomlines 


Any  changes  you  have  made  to  the  property  sheet  will  now  take  effect. 
Reset  the  property  sheet  to  the  state  it  had  at  the  time  of  the  last  Apply. 
Close  the  property  sheet. 

Advance  to  the  next  difference  after  each  Left  or  Rightoperation. 
Number  of  lines  in  the  top  two  subwindows. 

Number  of  lines  in  the  bottom  subwindow. 


Columns  Number  of  columns  in  the  left  (and  also  right)  subwindow. 

FILES 

7.  filemergerc  file  storing  property  sheet  information 

filemerge.out  default  output  file 
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SEE  ALSO 

diff(l),  sdiff(lV),  textedit(l) 

BUGS 

Using  the  Find  function  key  gets  the  subwindows  out  of  sync  for  scrolling.  To  resync  them,  turn  Scroll- 
Lock  first  off,  and  then  on. 


374 


Last  change:  9  September  1987 


Sun  Release  4.1 


OLD-MAKE(l) 


USER  COMMANDS 


OLD-MAKE(l) 


NAME 

old-make  -  maintain,  update,  and  regenerate  groups  of  programs 
SYNOPSIS 

/usr/old/make  [  — f  makefile  ] . . .  [  —bdeikmnpqrsSt  ]  [  target . . .  ]  [  macro-name  =value  . . .  ] 
DESCRIPTION 

make  executes  a  list  of  shell  commands  associated  with  each  target,  typically  to  create  or  update  a  file  of 
the  same  name,  makefile  contains  entries  for  targets  that  describe  how  to  bring  them  up  to  date  with 
respect  to  the  files  and/or  other  targets  on  which  each  depends,  called  dependencies. 

A  target  is  out  of  date  when  the  file  it  describes  is  missing,  or  when  one  (or  more)  of  its  dependency  files 
has  a  more  recent  modification  time  than  that  of  the  target  file,  make  recursively  scans  the  list  of  depen¬ 
dencies  for  e^h  target  argument  (or  the  first  target  entry  in  the  makefile  if  no  target  argument  is  supplied) 
to  generate  a  list  of  targets  to  check.  It  then  checks,  from  the  bottom  up,  each  target  against  any  files  it 
depends  on  to  see  if  it  is  out  of  date.  If  so,  make  rebuilds  that  target. 

To  rebuild  a  target,  make  executes  the  set  of  shell  commands,  called  a  rule,  associated  with  it.  This  rule 
may  be  listed  explicitly  in  a  makefile  entry  for  that  target,  or  it  may  be  supplied  implicitly  by  make. 

If  no  makefile  is  specified  on  the  command  line,  make  uses  the  first  file  it  finds  with  a  name  from  the  fol¬ 
lowing  list: 

makefile,  Makefile,  s.makefile,  s.Makefile,  SCCS/s.makefile,  SCCS/s.Makefile. 

If  no  target  is  specified  on  the  command  line,  make  uses  the  first  target  defined  in  makefile.  If  a  target  has 
no  makefile  entry,  or  if  its  entry  has  no  rule,  make  attempts  to  update  that  target  using  an  implicit  rule. 

OPTIONS 

-f  makefile 

Use  the  description  file  makefile.  A  as  the  makefile  argument  denotes  the  standard  input.  The 
contents  of  makefile,  when  present,  override  the  builtin  rules.  When  more  than  one  "-^makefile" 
argument  pairs  appear,  make  lakes  input  from  each  makefile  in  the  order  listed  (just  as  if  they 
were  run  through  cat(l  V)). 

-b  This  option  has  no  effect,  but  is  present  for  compatibility  reasons. 

-d  Debug  mode.  Print  out  detailed  information  on  files  and  times  examined. 

-e  Environment  variables  override  assignments  within  makefiles. 

-i  Ignore  error  codes  returned  by  invoked  commands. 

-k  When  a  nonzero  error  status  is  returned  by  an  invoked  command,  abandon  work  on  the  current 
target  but  continue  with  other  branches  that  do  not  depend  on  that  target. 

-n  No  execution  mode.  Print  commands,  but  do  not  execute  them.  Even  lines  beginning  with  an  @ 
are  printed.  However,  if  a  command  line  contains  the  $(MAKE)  macro,  that  line  is  always  exe¬ 
cuted  (see  the  discussion  of  MAKEFLAGS  in  Environment  Variables  and  Macros). 

-p  Print  out  the  complete  set  of  macro  definitions  and  target  descriptions. 

— q  Question  mode,  make  returns  a  zero  or  nonzero  status  code  depending  on  whether  or  not  the  tar¬ 

get  file  is  up  to  date. 

-r  Do  not  use  the  implicit  rules  make  supplies  by  default.  Implicit  rules  defined  in  the  makefile 
remain  in  effect. 

-s  Silent  mode.  Do  not  print  command  lines  before  executing  them. 

-S  Undo  the  effect  of  the  -k  option. 

-t  Touch  the  target  files  (bringing  them  up  to  date)  rather  than  performing  commands  listed  in  their 
rules. 
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macro-name  =value 

Macro  definition.  This  definition  overrides  any  definition  for  the  specified  macro  that  occurs  in 
the  makefile  itself,  or  in  the  environment.  See  Macros  and  Environment  Variables  and  Macros, 
for  details. 

USAGE 

Refer  to  SunOS  User’s  Guide:  Doing  More  and  Programming  Utilities  and  Libraries  for  tutorial  informa¬ 
tion  about  make. 

Targets  and  Rules 

There  need  not  be  an  actual  file  named  by  a  target,  but  every  dependency  in  the  dependency  list  must  be 
either  the  name  of  a  file,  or  the  name  of  another  target. 

If  the  target  has  no  dependency  list  and  no  rule,  or  if  the  target  has  no  entry  in  the  makefile,  make  attempts 
to  produce  an  entry  by  selecting  a  rule  from  its  set  of  implicit  rules.  If  none  of  the  implicit  rules  apply, 
make  uses  the  rule  specified  in  the  .DEFAULT  target  (if  it  appears  in  the  makefile).  Otherwise  make  stops 
and  produces  an  error  message. 

Makefile  Target  Entries 

A  target  entry  has  the  following  format: 

target . . . :  [dependency] . . .  [;  command] . . . 

[command] 

The  first  line  contains  the  name  of  a  target  (or  a  space-separated  list  of  target  names),  terminated  with  a 
colon  (:).  This  may  be  followed  by  a  dependency  ^  or  a  dependency  list  that  make  checks  in  the  order 
listed.  The  dependency  list  may  be  terminated  with  a  semicolon  (;),  which  in  turn  can  be  followed  by  a 
Bourne  shell  command.  Subsequent  lines  in  the  target  entry  begin  with  a  TAB,  and  contain  Bourne  shell 
commands.  These  commands  comprise  a  rule  for  building  the  target,  and  are  performed  when  the  target  is 
updated  by  make. 

Shell  commands  may  be  continued  across  input  lines  by  escaping  the  NEWLINE  with  a  backslash  (\).  The 
continuing  line  must  also  start  with  a  TAB. 

To  rebuild  a  target,  make  expands  any  macros,  strips  off  initial  TAB  characters  and  passes  each  resulting 
command  line  to  a  Bourne  shell  for  execution. 

The  first  nonblank  line  that  does  not  begin  with  a  TAB  or  #  begins  another  target  or  macro  definition. 
Makefile  Special  Characters 

::  Conditional  dependency  branch.  When  used  in  place  of  a  colon  (:)  the  double-colons  allow  a  tar¬ 

get  to  be  checked  and  updated  with  respect  to  more  than  one  dependency  list.  The  double-colons 
allow  the  target  to  have  more  than  one  branch  entry  in  the  makefile,  each  with  a  different  depen¬ 
dency  list  and  a  different  rule,  make  checks  each  branch,  in  order  of  appearance,  to  see  if  the  tar¬ 
get  is  outdated  with  respect  to  its  dependency  list.  If  so,  make  updates  the  target  according  to 
dependencies  and  rule  for  that  branch. 

#  Start  a  comment.  The  comment  ends  at  the  next  NEWLINE. 

$  Macro  expansion.  See  Macros,  below,  for  details. 

~  Following  the  TAB,  if  the  first  character  of  a  command  line  is  a  make  ignores  any  nonzero 
error  code  it  may  return,  make  normally  terminates  when  a  command  returns  nonzero  status, 
unless  the  -i  or  -k  options  are  in  effect. 

@  Following  the  TAB,  if  the  first  character  is  a  make  does  not  print  the  command  line  before 
executing  it. 

If  and  appear  as  the  first  two  characters  after  the  TAB,  both  apply. 

$$  The  dollar-sign,  escaped  from  macro  expansion.  Can  be  used  to  pass  variable  expressions  begin¬ 
ning  with  $  to  the  shell. 
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Command  Execution 

Command  lines  are  executed  one  at  a  time,  each  by  its  own  shell.  Shell  commands,  notably  cd,  are  ineffec- 
tual  across  an  unescaped  NEWLINE  in  the  makefile.  A  line  is  printed  (after  macro  expansion)  as  it  is  exe¬ 
cuted,  unless  It  starts  with  a  ‘(S)’,  there  is  a  .SILENT  entry  in  the  dependency  hierarchy  of  the  current  target, 
or  make  is  run  with  the  ~s  option.  Although  the  -n  option  specifies  printing  without  execution,  lines  con¬ 
taining  the  macro  $(MAKE)  are  executed  regardless,  and  lines  containing  the  @  special  character  are 
printed.  The  -t  (touch)  option  updates  the  modification  date  of  a  file  without  executing  any  rules.  This  can 
be  dangerous  when  sources  are  maintained  by  more  than  one  person. 

To  take  advantage  of  the  Bourne  shell  if  control  structure  for  branching,  use  a  command  line  of  the  form* 

if 

expressioni  \ 

then 

command;  \ 
command  ;\ 

elif 

expression ;  \ 


else 

command;  \ 

fi 

Although  composed  of  several  input  lines,  the  escaped  NEWLINE  characters  insure  that  make  treats  them 
all  as  one  command  line.  To  take  advantage  of  the  Bourne  shell  for  control  statement,  use  a  command  line 
of  the  form: 

for  var  in  list ;  do  \ 
command  ;  \ 


done 

To  write  shell  variables,  use  double  dollar-signs  ($$).  This  escapes  expansion  of  the  dollar-sign  by  make. 
Signals 

INT  and  QUIT  signals  received  from  the  keyboard  halt  make  and  remove  the  target  file  being  processed 
(unless  it  is  in  the  dependency  list  for  .PRECIOUS). 


Special-Function  Targets 

When  incorporated  in  a  makefile,  the  following  target  names  perform  special  functions. 

.DEFAULT  If  this  target  is  defined  in  the  makefile,  its  rule  is  used  when  there  is  no  entry  in  the  makefile 
for  a  given  target  and  none  of  the  implicit  rules  ^plies.  make  ignores  the  dependency  list 
for  this  target. 

.PRECIOUS  List  of  files  not  to  delete.  Files  listed  as  dependencies  for  this  target  are  not  removed  if 
make  is  interrupted  while  rebuilding  them. 

.SILENT  Run  silently.  When  this  target  appears  in  the  makefile,  make  does  not  echo  commands 
before  executing  them. 


JGNORE  Ignore  errors.  When  this  target  api^ars  in  the  makefile,  make  ignores  nonzero  error  codes 
returned  from  commands. 


.SUFFIXES  The  suffixes  list  for  selecting  implicit  rules  (see  Implicit  Rules). 

Include  Files 

make  has  an  include  file  capability.  If  the  word  include  appears  as  the  first  seven  letters  of  a  line,  and  is 
followed  by  a  SPACE  or  a  TAB,  the  string  that  follows  is  taken  as  a  filename.  The  text  of  the  named  file  is 
read  in  at  the  current  location  in  the  makefile,  include  files  can  be  nested  to  a  depth  of  no  more  than  about 
16. 
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Macros 

Entries  of  the  form 

macro-name -value 

define  macros,  name  is  the  name  of  the  macro,  and  value,  which  consists  of  all  characters  up  to  a  comment 
character  or  unescaped  NEWLINE,  is  the  value.  Words  in  a  macro  value  are  delimited  by  SPACE,  TAB,  and 
escaped  NEWLINE  characters,  and  the  terminating  NEWLINE. 

Subsequent  references  to  the  macro,  of  the  forms:  $iname)  or  %{name)  are  replaced  by  value.  The 
parentheses  or  brackets  can  be  omitted  in  a  reference  to  a  macro  with  a  single-character  name. 

Macros  definitions  can  contain  references  to  other  macros,  but  the  nested  references  aren’t  expanded 
immediately.  Instead,  they  are  expanded  along  with  references  to  the  macro  itself. 

Substitutions  within  macros  can  be  made  as  follows: 

%{name\strl=str2) 

where  strl  is  either  a  suffix,  or  a  word  to  be  replaced  in  the  macro  definition,  and  str2  is  the  replacement 
suffix  or  word. 

Dynamically  Maintained  Macros 

There  are  several  dynamically  maintained  macros  that  are  useful  as  abbreviations  within  rules. 

$*  The  basename  of  the  current  target.  It  is  assigned  only  for  implicit  rules. 

$<  The  name  of  the  file  on  which  the  target  is  assumed  to  depend.  This  macro  is  only  assigned  for 

implicit  rales,  or  within  the  .DEFAULT  target’s  rule. 

$@  The  name  of  the  current  target.  It  is  assigned  only  for  rales  in  targets  that  are  explicitly  defined  in 
the  makefile. 

$?  The  list  of  dependencies  with  respect  to  which  the  target  is  out  of  date.  This  macro  is  assigned 
only  for  explicit  rules. 

$%  The  library  member.  The  $%  macro  is  only  evaluated  when  the  target  is  an  archive  library 
member  of  the  form:  lib(Jile,o ).  In  this  case,  $@  evaluates  to  lib  and  $%  evaluates  to  the  library 
member,  yi/e.o. 

All  of  these  macros  but  $?  can  be  modified  to  apply  either  to  the  filename  part,  or  the  directory  part  of  the 
strings  they  stand  for,  by  adding  an  upper  case  F  or  D,  respectively  (and  enclosing  the  resulting  name  in 
parentheses  or  braces).  Thus,  ‘$(@D)’  refers  to  the  directory  part  of  the  string  If  there  is  no  direc¬ 
tory  part,  is  generated. 

Environment  Variables  and  Macros 

After  reading  in  its  implicit  rules,  make  reads  in  variables  from  the  environment,  treating  them  as  if  they 
were  macro  definitions.  Only  then  does  make  read  in  a  makefile.  Thus,  macro  assignments  within  a 
makefile  override  environment  variables,  provided  that  the  -e  option  is  not  in  effect.  In  turn,  make  exports 
environment  variables  to  each  shell  it  invokes.  Macros  not  read  in  from  the  environment  are  not  exported. 

The  MAKEFLAGS  macro  is  a  special  case.  When  present  as  an  environment  variable,  make  takes  its 
options  (except  for  -f,  -p,  and  -d)  from  MAKEFLAGS  in  combination  with  any  flags  entered  on  the  com¬ 
mand  line,  make  retains  this  combined  value,  exports  it  automatically  to  each  shell  it  forks,  and  reads  its 
value  to  obtain  options  for  any  make  commands  it  invokes.  Note,  however  that  flags  passed  with 
MAKEFLAGS  even  though  they  are  in  effect,  are  not  shown  in  the  output  produced  by  make. 

The  MAKE  macro  is  another  special  case.  It  has  the  value  make  by  default,  and  temporarily  overrides  the 
-n  option  for  any  line  that  contains  a  reference  to  it.  This  allows  nested  invocations  of  make  written  as: 

$(MAKE)... 

to  run  recursively,  so  that  the  command  make  -n  can  be  used  to  test  an  entire  hierarchy  of  makefiles. 
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For  compatibility  with  the  4.2  BSD  make,  the  MFLAGS  macro  is  set  from  the  MAKEFLAGS  variable  by 
prepending  a  MFLAGS  is  not  exported  automatically. 


make  supplies  the  following  macros  for  compilers  and  their 

options: 

CC 

C  compiler,  cc(lV) 

CFLAGS 

C  compiler  options 

FC 

FORTRAN  77  compiler,  n7(l) 

FFLAGS 

RFLAGS 

FORTRAN  77  compiler  options 
FORTRAN  77  compiler  options  with 
Ratfor  (.r)  source  files 

PC 

Pascal  compiler,  pc  (1) 

PFLAGS 

Pascal  compiler  options 

M2C 

Modula-2  compiler 

M2FLAGS 

Modula-2  compiler  options 

GET 

sees  (1)  get  command 

GFLAGS 

secs  get  options 

AS 

the  assembler,  as(l) 

ASFLAGS 

assembler  options 

LD 

the  linker,  Id  (1) 

LDFLAGS 

linker  options 

LEX 

lex(l) 

LFLAGS 

lex  options 

YACC 

yacc  (1) 

YFLAGS 

yacc  options 

Unless  these  macros  are  read  in  as  environment  variables,  their  values  are  not  exported  by  make.  If  you 
run  make  with  any  these  set  in  the  environment,  it  is  a  good  idea  to  add  commentary  to  the  makefile  to 
indicate  what  value  each  takes.  If  -r  is  in  effect,  make  ignores  these  macro  definitions. 

When  set  to  a  single-word  value  such  as  /usr/bin/csh,  the  SHELL  macro  indicates  the  name  of  an  alternate 
shell  to  use  for  invoking  commands.  Note:  to  improve  normal  performance  make  executes  command  lines 
that  contain  no  shell  metacharacters  directly.  Such  builtin  commands  as  dirs,  or  set  in  the  C  shell  are  not 
recognized  unless  the  command  line  includes  a  metacharacter  (for  instance,  a  semicolon). 

Implicit  Rules 

make  supplies  implicit  rules  for  certain  types  of  targets  that  have  no  explicit  rule  defined  in  the  makefile. 
For  these  types  of  targets,  make  attempts  to  select  an  implicit  rule  by  looking  for  an  association  between 
the  target  and  a  file  in  the  directory  that  shares  its  basename.  That  file,  if  found,  is  presumed  to  be  a  depen¬ 
dency  file.  The  implicit  rule  is  selected  according  to  the  target’s  suffix  (which  may  be  null),  and  that  of  the 
dependency  file.  If  there  is  no  such  dependency  file,  if  the  suffix  of  either  dependency  or  target  is  not  the 
suffixes  list,  or  if  there  is  no  implicit  rule  defined  for  that  pair  of  suffixes,  no  rule  is  selected,  make  either 
uses  the  default  rule  that  you  have  supplied  (if  any),  or  stops. 

The  suffixes  list  is  a  target  with  each  known  suffix  listed  as  a  dependency,  by  default: 

.SUFFIXES;  .o  .c  .c~  .mod  .mod~  .sym  .def  .def*"  .p  .p~  .f  .f~  .r  .r~  .y  .y*“  .1  .1~ 

.s  .s~  .sh  .sh~  .h  .h~ 

Multiple  suffix-list  targets  accumulate;  a  .SUFFIXES  target  with  no  dependencies  clears  the  list  of  suffixes. 
Order  is  significant;  make  selects  a  rule  that  corresponds  to  the  target’s  suffix  and  the  first  dependency-file 
suffix  found  in  the  list. 

A  tilde  (-)  refers  to  the  s,prefix  of  an  SCCS  history  file  (see  sccs(l)).  If  make  cannot  locate  a  history  file 
(with  a  name  of  the  form  s.basename. suffix)  in  the  current  working  directory,  it  checks  for  one  in  the  SCCS 
subdirectory  (if  that  directory  exists)  for  one  from  which  to  sccs-get(l)  the  dependency  file. 

An  implicit  rule  is  a  target  of  the  form: 
dt: 

rule 

where  t  is  the  suffix  of  the  target,  d  is  the  suffix  of  the  dependency,  and  rule  is  the  implicit  rule  for  building 
such  a  target  from  such  a  dependency.  Both  d  and  t  must  appear  in  the  suffixes  list  for  make  to  recognize 
the  target  as  one  that  defines  an  implicit  rule. 

An  implicit  rule  with  only  one  suffix  describes  how  to  build  a  target  having  a  null  (or  no)  suffix,  from  a 
dependency  having  the  indicated  suffix.  For  instance,  the  .c  rule  describes  how  to  build  the  executable  file 
from  a  C  source  file,yi/e.c. 
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Implicit  rules  are  supplied  for  the  following  suffixes  and  suffix  pairs: 

*c  .c  ♦p  .p  ,mod  .mod~  .f  .f~  .F  .r  .r~  .sh~  .c.o  .c~.o  .c~,c  .p,o  ,p~.o  .p~.p 
.mod.o  .mod~.o  .mod~.mod  .def^ym  .def~.sym  .def~.def  .f.o  .f~.f  .F.o  .F~.o  ,F*~.F  .r.o 
.r^.o  .r  .r  .s  .o  .s  ^  ^h~.sh  .y.o  .y~.o  J.o  .l~.o  .y.c  ,y~.c  .y~.y  .Lc  .l~.c  .l~.l  .c.a 
.c  .a.s  .a  .h^.h 

These  rules  can  be  changed  within  a  makefile,  and  additional  implicit  rules  can  be  added.  To  print  out 
makers  internal  rules,  use  the  following  command.  Note:  this  command  only  works  with  the  Bourne  Shell: 

$  make  -fp  -  2>/dev/null  </dev/null 

If  you  are  using  the  C  shell,  use  this  command  to  print  out  make’s  internal  rules: 


example%  (make  -fp  -  </dev/null  >/dev/tty)  >&/dev/null 
Library  Maintenance 

If  a  target  name  contains  parentheses,  as  with: 
lib.a(member) 

it  is  assumed  to  be  the  name  of  an  archive  (ar(lV))  library.  The  string  within  the  parentheses  refers  to  a 
member  of  the  library.  (If  the  string  contains  more  than  one  word,  the  only  first  word  is  used.)  A  member 
of  an  archive  can  be  explicitly  made  to  depend  on  a  file  with  a  matching  filename.  For  instance,  given  a 
directory  that  contains  the  files  meml.c  and  mem2.c,  along  with  a  makefile  with  the  entries: 

lib.a:  lib.a(meml.o)  lib.a(mem2.0) 

lib.a(meml.o):  meml.o 

ar  rv  Ub.a  meml.o 

Hb*a(mem2.o):  mem2.o 

ar  rv  Ub.a  mem2.o 

make,  when  run,  compiles  the  .c  files  into  relocatable  object  (,o)  files  using  the  .c.o  implicit  rule.  It  then 
loads  the  freshly  compiled  version  of  each  file  into  the  library  according  to  the  explicit  rules  in  the 
lib.aOtargets. 

Implicit  rules  pertaining  to  archive  libraries  have  the  form  .XX, a  where  the  XX  is  the  suffix  from  which  the 
archive  member  is  to  be  made.  An  unfortunate  byproduct  of  the  current  implementation  requires  that  XX  to 
be  different  from  the  suffix  of  the  archive  member  itself.  For  instance,  the  target  lihifile.o)  cannot  depend 
upon  the  file,o  explicitly,  but  instead,  must  be  made  to  depend  on  a  source  file,  such  as  For  this  rea¬ 
son  it  is  recommended  that  you  define  an  explicit  target  in  the  makefile  for  each  library  member  to  main¬ 
tain,  as  shown  above. 

A  target  name  of  the  form 

library  ({entry-point)) 

refers  to  the  member  of  a  randomized  object  library  (see  ranlib(l))  that  defines  the  symbol  entry-point. 
EXAMPLES 

This  makefile  says  that  pgm  depends  on  two  files  a.o  and  b.o,  and  that  they  in  turn  depend  on  their 
corresponding  source  files  (a.c  and  b.c)  along  with  a  common  file  incLh: 

pgm:  a.o  b.o 

cc  a.o  b.o  -0  $@> 

a. o:  incl.h  a.c 

cc  -c  a.c 

b. o:  incl.h  b.c 

cc  -c  b.c 
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The  following  makefile  uses  the  builtin  inference  rules  to  express  the  same  dependencies; 

pgm:  a.o  b.o 

cc  a.o  b.o  -0  pgm 

a.o  b.o:  incl.h 

FILES 

[Mm]akefile 

s.[Mm\akefile 

SCCS/s.[mM]akefile 

DIAGNOSTICS 

Don’t  know  how  to  make  target .  Stop. 

There  is  no  makefile  entry  for  target,  and  none  of  make’s  implicit  rules  apply  (there  is  no  depen¬ 
dency  file  with  a  suffix  in  the  suffixes  list,  or  the  target’s  suffix  is  not  in  the  list). 

***  target  removed. 

make  was  interrupted  in  the  middle  of  trying  to  build  target.  Rather  than  leaving  a  partially- 
completed  version  that  is  newer  than  its  dependencies,  make  removes  the  file  associated  with  tar¬ 
get. 

***  Error  code  n. 

The  previous  shell  command  returned  a  nonzero  error  code.  In  this  case  make  stops,  unless  either 
the  -k  or  the  -i  option  is  set,  the  target  .IGNORE  appears,  or  the  command  is  prefixed  with  a 
in  the  makefile. 

***  signal  message 

The  previous  shell  command  was  aborted  due  to  a  signal.  If  core  dumped*  appears  after  the 
message,  a  core  file  was  created. 

SEE  ALSO 

ar(lV),  cat(lV),  cc(lV),  cd(l),  csh(l),  lex(l),  ranlib(l),  sccs(l),  sccs-get(l),  sh(l) 

SunOS  User's  Guide:  Doing  More 
Programming  Utilities  and  Libraries 

BUGS 

Some  commands  return  nonzero  status  inappropriately;  use  -i  to  ovCTcome  the  difficulty. 

Filenames  with  the  characters  =, :,  and  @  will  not  work. 

You  cannot  build  \ib{file.o)  from  filejo. 

The  macro  substitution  $(a:.o=.c")  does  not  work. 

Options  supplied  by  MAKEFLAGS  should  appear  in  output  from  make. 


/'  \ 
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NAME 

old-prmail  -  display  waiting  mail 
SYNOPSIS 

/usr/old/prmail  [  user  ]... 

DESCRIPTION 

Note:  This  program  is  considered  to  be  obsolete,  and  will  not  be  distributed  or  supported  in  future  Sun 
releases. 

prmail  displays  waiting  mail  for  you,  or  the  specified  users.  The  mail  is  not  disturbed. 

FILES 

/var/spool/mail/*  waiting  mail  files 
SEE  ALSO 

biff(l),  bm-mail(l),  from(l),  mail(l) 
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NAME 

old-pti  “  phototypeselter  interpreter 
SYNOPSIS 

/usr/old/pti  [filename ...] 

DESCRIPTION 

Note:  This  program  is  considered  to  be  obsolete,  and  will  not  be  distributed  or  supported  in  future  Sun 
releases. 

pti  shows  the  commands  in  a  stream  from  the  standard  output  of  troff(l)  using  troff ’s  option,  interpret¬ 
ing  the  commands  as  they  would  act  on  the  typesetter.  Horizontal  motions  show  as  counts  in  internal  units 
and  are  marked  with  <  and  >  indicating  left  and  right  motion.  Vertical  space  is  called  leading  and  is  also 
indicated. 

The  output  is  really  cryptic  unless  you  are  an  experienced  C/A/T  hardware  person.  It  is  better  to  use 
‘troff  -a*. 

SEE  ALSO 

troff(l) 
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NAME 

old-setkeys  -  modify  interpretation  of  the  keyboard 
SYNOPSIS 

/usr/old/setkeys  [  reset  I  nosunview  I  [  [  lefty  ]  [  noarrows  ]  ]  ]  [  sunl  I  sun2  I  sun3  ] 

Sun386i  SYNOPSIS 

setkeys  [  reset  I  nosunview  I  [  [  lefty  ]  [  noarrows  ]  ]  ]  [  sunl  I  sun2 !  sun3i  sun4  ] 

DESCRIPTION 

setkeys  has  been  superseded  by  the  Input  category  in  defaultsedit(l),  and  by  the  program 
input_froni_defaults  (1).  It  is  retained  for  backwards  compatibility  on  Sun-2,  Sun-3  and  Sun-4  systems. 

Sun386i  DESCRIPTION 

setkeys  changes  the  kernel’s  keyboard  translation  tables,  converting  a  keyboard  to  one  of  a  number  of 
commonly  desired  configurations.  It  takes  an  indication  of  the  modifications  to  be  i>erformed,  and  option¬ 
ally,  the  kind  of  keyboard  attached  to  the  user’s  machine.  It  affects  all  keyboard  input  for  the  machine  it  is 
run  on  (in  or  out  of  the  window  system)  until  that  effect  is  superseded  by  rebooting,  or  by  running  ‘setkeys 
reset’. 

OPTIONS 

modifications 

Empty,  or  one  of  reset,  nosunview,  or  some  combination  of  lefty  and  noarrows.  By  default,  the 
keyboard  is  set  to  produce  the  Sun  View  function-key  codes  (Stop,  Props,  Front,  Close,  Find, 
Again,  Undo,  Copy,  Paste  and  Cut;  SunView  User’s  Guide.  On  Sun-2  and  Sun-3  keyboards,  this 
is  meaningless;  on  the  Sun-1,  those  functions  are  assigned  to  two  columns  of  the  right  numeric- 
function  pad. 

lefty  Indicate  the  SunView  functions  are  to  be  produced  from  keys  on  the  right  side  of  the  keyboard, 
convenient  for  using  the  mouse  in  the  left  hand. 

On  the  Sun-2  and  Sun-3  systems,  the  SunView  functions  are  reflected  to  the  outside  columns  of 
the  right  function  pad;  those  right-side  functions  are  distributed  in  a  more  complicated  fashion  dic¬ 
tated  by  keeping  the  arrow  keys  together;  see  below.  Also,  the  Line  Feed  key,  immediately  below 
Return,  is  converted  to  a  second  Control. 

On  the  Sun-1,  lefty  is  the  same  as  the  default,  since  there  is  no  left  function  pad. 
noarrows 

Reassign  the  keys  with  cursor  arrows  on  their  caps  to  produce  simple  function  codes  (so  they  may 
be  used  with  filters  in  the  textsw,  or  mapped  input  in  the  ttysw). 

nosunview 

Only  valid  on  Sun-2  and  Sun-3  keyboards,  or  on  a  Sun-4  keyboard  used  with  386i  architecture, 
nosunview  is  incompatible  with  lefty,  noarrows,  or  reset.  This  option  assigns  new  codes  to  keys 
FI  and  L2  -  LIO,  codes  that  are  not  normally  produced  anywhere  on  the  keyboard.  These  codes 
may  be  selected  by  a  mapi  or  mapo  operation  defined  in  a  user’s  .ttyswrc  file. 

This  option  supports  a  measure  of  backwards  compatibility  to  programs  that  apply  some  other 
interpretation  to  the  affected  function  keys.  It  allows  them  to  access  the  new  codes  when  the  stan¬ 
dard  codes  would  be  preempted  by  SunView  functions  (for  instance,  in  a  tty(l)  subwindow). 

reset  Incompatible  with  lefty,  noarrows,  or  nosunview;  it  causes  the  keyboard  to  be  reset  to  its  original 
interpretation. 

keyboard-type 

One  of  sunl,  sun2,  or  sun3.  sun4  is  available  with  386i  architecture  only.  Normally,  this  option 
is  omitted;  the  type  of  keyboard  attached  to  the  system  is  obtained  from  the  kernel.  If  included, 
the  option  is  believed  in  preference  to  the  kernel’s  information,  setkeys  treats  Sun-2  and  Sun-3 
keyboards  identically  except  when  the  modification  is  reset. 
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Note:  The  keyboard  type  is  not  necessarily  the  same  as  the  machine  type.  A  Sun-1  keyboard  is 
the  VTlOO-style  keyboard  shipped  with  Model  lOOUs,  while  Sun-2  and  Sun-3  keyboards  may 
attached  interchangeably  to  Sun-2  and  Sun-3  machines.  A  Sun-3  keyboard  is  distinguished  by 
aerodynamic  housing,  and  the  presence  of  Caps  and  Alternate  keys. 

Options  may  appear  in  any  order,  and  case  is  not  significant.  The  accompanying  diagrams  show  the  exact 
distribution  of  codes  for  each  combination  of  keyboard  and  arguments  to  setkeys. 

EXAMPLES 

The  command 

setkeys  lefty  noarrows 

puts  the  SunView  functions  on  the  right  pad  of  the  keyboard,  replacing  arrow  keys  by  the  corresponding 
right-function  codes,  and  displacing  right-function  codes  to  the  left  pad. 

The  command: 

setkeys  sunl  reset 

restores  a  Sun-1  keyboard  to  its  original  arrangement. 

SEE  ALSO 

defaultsedit(l),  mput_from_defaults(l),  kb(4M) 

SunView  User’s  Guide 


BUGS 

setkeys  affects  the  kernel’s  key  tables,  which  in  turn  affects  all  users  logged  in  to  the  system. 
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NAME 

old-sun3cvt  -  convert  large  Sun-2  system  executables  to  Sun-3  system  executables 
SYNOPSIS 

/usr/old/sun3cvt  [  oldfile  [  newfile  ]  ] 

DESCRIPTION 

Note:  This  program  is  considered  to  be  obsolete,  and  will  not  distributed  or  supported  in  future  Sun 
releases. 

sun3cvt  converts  an  old  Sun-2  system  program  file  (predating  Sun  release  3.0)  into  a  Sun-3  system  execut¬ 
able  file. 

The  default  oldfile  is  a*out.  The  default  newfile  is  sun3.out. 

sun3cvt  attempts  to  create  a  file  of  the  same  type  (magic  number).  However,  for  sharable-text  files  with 
less  than  I28kb  of  text,  the  new  file  will  not  be  sharable  (since  Sun-3  data  segments  must  begin  on  128kb 
boundaries).  Also,  most  programs  have  some  text  in  the  data  segment  as  a  consequence  of  the  new  larger 
Sun-3  system  page  and  segment  sizes. 

execve(2V)  executes  an  old  Sun-2  system  program  file,  but  the  program’s  text  is  not  sharable.  Old  pure- 
text  programs  with  text  segments  larger  than  128kb  can  be  made  sharable  on  machines  running  release  3.0 
or  subsequent  releases  by  using  sun3cvt 

FILES 

a.out  default  oldfile 

sun3.out  default  newfile 

SEE  ALSO 

execve(2V) 
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NAME 

old-syslog  -  make  a  system  log  entry 
SYNOPSIS 

/usr/old/syslog  [  —  ]  [  -p  ]  [  — i  name  ]  [  -level  ]  [  message . . .  ] 

DESCRIPTION 

Note:  this  program  is  considered  to  be  obsolete,  and  will  not  distributed  or  supported  in  future  Sun 
releases.  See  logger(l)  to  add  system  log  entries. 

syslog  sends  the  specified  message  (or  the  standard  input  if  ’  is  specified)  as  a  system  log  entry  to  the 
syslog  daemon.  The  log  entry  is  sent  to  the  daemon  on  the  machine  specified  by  the  loghost  entry  in  the 
/etc/hosts  file. 

OPTIONS 

-  Each  line  of  the  standard  input  is  sent  as  a  log  entry. 

-p  syslog  logs  its  process  ID  in  addition  to  the  other  information. 

-i  name  Specify  the  name  to  be  used  as  the  “ident”  for  the  log  entry. 

-level  The  message  will  be  logged  at  the  specified  level.  The  level  can  be  specified  numerically,  in  the 
range  1  through  9,  or  symbolically  using  the  names  specified  in  the  include  file  <syslog.h>  (with 
the  leading  LOG_^  stripped  off).  syslog-HELP  lists  the  valid  symbolic  level  names.  Only  the 
super-user  can  make  log  entries  at  levels  less  than  or  equal  to  SALERT. 

FILES 

/usr/etc/syslogd  syslog  daemon 

SEE  ALSO 

logger(l),  syslog(3),  sysIogd(8) 


388 


Last  change:  31  March  1987 


Sun  Release  4.1 


OLD-VC(l) 


USER  COMMANDS 


OLD-VC(l) 


NAME 

old-vc  “  version  control 
SYNOPSIS 

/usr/old/vc  [  -a  ]  [  -s  ]  [  -t  ]  [  -cc  ]  [  k£yword=value]. . . 

DESCRIPTION 

The  VC  command  copies  lines  from  the  standard  input  to  the  standard  output  under  control  of  its  arguments 
and  the  control  statements  encountered  in  the  standard  input.  In  the  process  of  performing  the  copy  opera¬ 
tion,  a  reference  to  a  user-declared  keyword  is  replaced  by  its  character-string  value ,  when  appearing  in  a 
plain  text  line  or  control  statement 

Copying  lines  from  the  standard  input  to  the  standard  output  is  conditional,  based  on  tests  (in  control  state¬ 
ments)  of  keyword  values  specified  either  in  control  statements,  or  as  vc  command-line  arguments. 

OPTIONS 

-a  Force  replacement  of  keyword  references  in  all  text  lines,  and  not  just  in  vc  statements. 

“S  Silent  Suppress  warning  messages  (but  not  error  messages)  that  are  normally  printed  on  the  diag¬ 
nostic  output. 

-t  If  a  TAB  character  appears  on  a  line,  all  characters  from  the  beginning  of  a  line,  up  to  and  includ¬ 
ing  the  first  TAB,  are  ignored  for  the  purpose  of  detecting  a  control  statement  If  the  TAB  precedes 
a  control  statement,  the  leading  text  is  discarded. 

-cc  Specify  an  alternate  control  character  to  use  instead  of 

USAGE 

vc  distinguishes  between  text  input  lines  and  version  control  statement  lines.  A  version  control  statement 
(control  statement)  is  a  single  line  beginning  with  a  control  character.  The  default  control  character  is 
colon  (:),  except  as  modified  by  the  -cc  option.  Input  lines  beginning  with  a  backslash  (\),  and  followed 
by  a  control  character,  are  not  control  lines  and  are  copied  to  the  standard  output  as  text  with  the  backslash 
removed.  Lines  beginning  with  a  backslash,  but  not  followed  by  a  control  character,  are  copied  in  their 
entirely. 

Keyword  Replacement 

A  keyword  is  composed  of  9  or  less  alphanumeric  characters;  the  first  must  be  alphabetic.  A  value  is  any 
printable  ASCII  character  or  character  string.  An  unsigned  string  of  digits  is  treated  as  a  numeric  value  in 
control  operations.  Keyword  values  may  not  contain  any  SPACE  or  TAB  characters. 

Keyword  replacement  is  performed  whenever  a  keyword,  surrounded  by  control  characters,  is  encountered 
on  a  version  control  statement.  The  -a  option  forces  replacement  of  keywords  in  all  lines  of  text.  An 
uninterpreted  control  character  may  be  included  in  a  value  by  preceding  it  with  ‘\’.  If  a  literal  ‘\’  is 
desired,  then  it  too  must  be  preceded  by  a  *  \  ’. 

Version  Control  Statements 
:  del  keywordijeeyword] 

Declare  a  keyword.  All  keywords  must  be  declared. 

:  sksg  keyword -value 

Assign  a  value  to  a  keyword.  An  asg  statement  overrides  any  previous  assignment  for  the 
corresponding  keyword,  including  those  on  the  vc  command  line.  Keywords  declared,  but  not 
assigned  values,  have  null  values. 
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:if  [not]  condition 

:end  Skip  Unes  of  the  standard  input.  When  condition  is  TRUE  ,  all  lines  between  the  if  statement  and 
the  matching  end  statement  are  copied  to  the  standard  output.  Otherwise,  the  intervening  lines  are 
discarded  and  ignored,  including  intervening  control  statements.  Intervening  if  and  end  control 
statements  are  recognized  solely  for  the  purpose  of  maintaining  the  proper  if-end  matching.  The 
not  argument  inverts  the  sense  of  the  condition.  When  it  is  used,  intervening  lines  are  included  in 
the  output  only  when  the  conditions  is  false. 

condition  is  a  logical  expression  composed  of  comparisons  and  logical  operators.  A  comparison 
consists  of  two  text  values  (may  be  keyword  references)  separated  by  a  comparison  operator. 
Each  value  rnust  be  separated  from  all  operators  by  at  least  one  SPACE  .  Numeric  strings  are 
treated  as  unsigned  integers  for  certain  comparisons.  The  comparison  operators  are: 

=  equal  (string) 

!=  not  equal  (string) 

>  greater  than  (numeric) 

<  less  than  (numeric) 

For  instance,  the  line: 

:\fxxxl=yyy 

tests  to  see  whether  the  string  *xxx^  is  not  equal  to  ‘yyy’,  which  is  true;  subsequent  intervening 
lines  are  therefore  included. 

The  logical  sense  of  comparisons  can  be  combined  using  the  logical  operators  (in  order  of  pre¬ 
cedence): 

( )  logical  grouping 

&  and 

I  or 

For  instance,  the  line 

:if  xxx=yyy\xxx  1=  yyy 

is  true  because  either  comparison  will  make  it  true,  while 
;if  XXX  =  yyy  &  XXX  !=  yyy 

is  false,  because  in  this  case,  both  comparisons  must  be  true. 

lUext  Force  keyword  replacement  on  lines  that  are  copied  to  the  standard  output,  independent  from  the 
-a  option.  The  two  leading  control  characters  are  removed,  and  keywords  surrounded  by  control 
characters  in  text  are  replaced  by  their  value  before  the  line  is  copied  to  the  output  file. 

:on 

:off  Turn  on  or  off  keyword  replacement  on  all  lines. 

:ctl  c  Change  the  control  character  to  c. 

;msg  message 

Print  message  on  the  diagnostic  output. 

:err  message 

Print  the  given  message,  followed  by: 

ERROR;  err  statement  on  line  . . .  (915) 
on  the  diagnostic  output;  vc  halts  execution,  and  returns  an  exit  code  of  1. 

SEE  ALSO 

sccs<help(l) 
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Use  sccs-help(l)  for  explanations. 
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NAME 

on  —  execute  a  command  on  a  remote  system,  but  with  the  local  environment 
SYNOPSIS 

on  [  -i  ]  [  -d  ]  [  -n  ]  host  command  [  argument  ] . . . 

DESCRIPTION 

The  on  program  is  used  to  execute  commands  on  another  system,  in  an  environment  similar  to  that  invok¬ 
ing  the  program.  All  environment  variables  are  passed,  and  the  current  working  directory  is  preserved.  To 
preserve  the  working  directory,  the  working  file  system  must  be  either  already  mounted  on  the  host  or  be 
exported  to  it.  Relative  path  names  will  only  work  if  they  are  within  the  current  file  system;  absolute  path 
names  may  cause  problems. 

The  standard  input  is  connected  to  the  standard  input  of  the  remote  command,  and  the  standard  output  and 
the  standard  error  from  the  remote  command  are  sent  to  the  corresponding  files  for  the  on  command. 

OPTIONS 

-i  Interactive  mode.  Use  remote  echoing  and  special  character  processing.  This  option  is  needed  for 
programs  that  expect  to  be  talking  to  a  terminal.  All  terminal  modes  and  window  size  changes  are 
propagated. 

-d  Debug  mode.  Print  out  some  messages  as  work  is  being  done. 

— n  No  Input.  This  option  causes  the  remote  program  to  get  EOF  when  it  reads  from  the  standard  input, 

instead  of  passing  the  standard  input  from  the  standard  input  of  the  on  program.  For  example,  -n 
is  necessary  when  running  commands  in  the  background  with  job  control. 

SEE  ALSO 

chkey(l),  publickey(5),  exports(5),  r€xd(8C) 

DIAGNOSTICS 

unknown  host  Host  name  not  found. 

cannot  connect  to  server 

Host  down  or  not  running  the  server. 

can’t  find  Problem  finding  the  working  directory, 

can’t  locate  mount  point 

Problem  finding  current  file  system.  RPC:  Authentication  error  The  server 
requires  des  authentication  and  you  do  not  have  a  secret  key  registered  with 
keyserv.  Perhaps  you  logged  in  without  a  password.  Try  to  keylogin.  If  that  fails 
try  to  set  your  publickey  with  chkey. 

Other  error  messages  may  be  passed  back  from  the  server. 

BUGS 

The  SunView  window  system  can  get  confused  by  the  environment  variables. 

When  the  working  directory  is  remote  mounted  over  NFS,  a  "Z  hangs  the  window. 

Root  cannot  use  on. 
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NAME 

organizer  -  file  and  directory  manager 
SYNOPSIS 

organizer  [  -A  time  ] 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0.^  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

organizer  is  a  Sun  View  application  for  viewing  and  manipulating  files  and  directories.  It  performs  many 
of  the  functions  of  the  Is(lV),  cd(l),  chniod(lV),  cp(l),  niv(l),  mkdir(l),  rmdir(see  rm(l)),  and 
dunip(8)  commands,  and  with  a  visual  interface. 

At  any  given  time,  the  organizer  window  normally  shows  the  files  and  directories  in  a  single  directory, 
representing  each  file  or  directory  with  an  appropriate  illustrated  icon.  The  illustration  indicates  whether  a 
file  is  a  directory,  contains  text,  is  an  executable  program,  or  optionally  a  user-defined  file  type. 

When  organizer  is  switched  into  Map  mode,  the  icons  are  arranged  to  indicate  the  hierarchy  of  files  and 
directories.  Double  clicking  on  a  directory  icon  shows  the  contents  of  that  directory  in  a  new  column. 

Several  display  modes  are  available,  and  can  be  set  for  an  individual  organizer  window  or  for  all  organ¬ 
izer  windows.  You  can  select  whether  hidden  files  are  shown,  whether  just  the  name,  the  name  and  infor¬ 
mation,  or  name  and  icon  are  shown  for  each  file  and  directory,  and  how  the  contents  are  sorted. 

Text  files  can  be  “edited”  by  double  clicking  on  the  file’s  icon.  The  contents  of  the  file  are  then  shown  and 
can  be  edited  in  a  separate  text  editor  window.  In  the  .orgrc  file  you  can  specify  the  EXECUTE,  EDIT,  and 
PRINT  applications  for  your  own  user-defined  file  types. 

You  can  move  down  through  the  directory  hierarchy  by  double  clicking  on  a  directory  icon,  and  up  by  dou¬ 
ble  clicking  on  the  parent  directory  name  on  the  ancestor  list  in  the  upper  left  comer  of  the  organizer 
panel. 

Copying,  moving,  and  deleting  require  you  to  select  one  or  more  files.  To  select  a  file,  click  the  left  button 
on  it  (do  not  double  click  —  this  will  open  the  file).  To  select  additional  files  to  be  operated  on,  click  the 
middle  button  on  each  additional  file. 

Copying  and  moving  operations  require  a  destination  directory.  After  the  files  are  selected,  change  direc¬ 
tories  to  the  desired  destination  as  described  above,  and  then  “drop”  the  files  with  the  Drop  button  on  the 
command  panel.  If  the  copy  involves  overwriting  an  identically  named  file,  an  alert  will  allow  you  to 
confirm  that  you  want  to  overwrite  the  file.  If  you  copy  a  file  and  then  “drop”  it  in  the  same  directory, 
organizer  will  prepend  copy_of_  to  the  file  name  of  the  new  file. 

OPTIONS 

-A  time  Sets  autoclose  for  time  minutes.  If  organizer  is  not  used  for  time  minutes,  it  closes  automatically. 

FILES 

/usr/include/images/+  file  and  directory  icons 
"/.orgrc 

. .  /.DeletedOrgFiles  organizer  creates  this  directory  to  store  files  so  you  can  undo  the  last  thing  you 
did,  for  example,  deleting  files. 

SEE  ALSO 

nikdir(l),  niv(l),  rm(l),  orgrc(5),  restore(8) 
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NAME 

overview  -  run  a  program  from  SunView  that  takes  over  the  screen 
SYNOPSIS 

overview  [ ~w  ]  [  generic _tool_options ]  program  name  [  arguments  ] . . . 

AVAILABILITY 

This  command  is  available  with  the  SunView  User's  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

Bitmap  graphics  based  programs  that  are  not  SunView  based  can  be  run  from  SunView  using  overview, 
overview  shows  an  icon  in  SunView  when  overview  is  brought  up  iconic  (-Wi  generic  tool  option;  see 
sunview(l))  or  when  the  program  being  run  by  overview  is  suspended  (for  example,  using  CTRL-Z). 
Opening  the  overview  icon,  or  starting  overview  non-iconic,  starts  the  program  named  on  the  command 
line,  overview  suppresses  SunView  so  that  SunView  window  applications  will  not  interfere  with  the 
program*s  display  output  or  input  devices. 

overview  runs  programs  that  fit  the  following  profile: 

own  display  The  program  needs  to  own  the  bits  on  the  screen.  It  does  not  use  the  sun- 

view  library  to  aibitrate  the  use  of  the  display  and  input  devices  between 
processes. 

keyboard  input  from  stdin  The  program  takes  keyboard  input  from  stdin  directly. 

mouse  input  from  /dev/mouse  The  program  takes  locator  input  from  the  mouse  directly. 

OPTIONS 

-w  This  option  is  used  to  specify  that  the  program  being  run  creates  its  own  SunWindows  window  in 
order  to  receive  the  serialized  input  stream  from  the  keyboard  and  mouse  that  is  provided  by  the 
SunWindows  kernel  driver.  ~w  tells  overview  to  not  convert  SunWindows  input  into  ASCII 
which  is  then  sent  to  the  program  being  run  under  overview  via  a  pty.  X  and  NeWS  are  programs 
that  fall  in  this  category  (as  of  Dec  86.  This  is  subject  to  change  in  the  future.) 

SEE  ALSO 

sunview(l) 

BUGS 

Users  of  overview  on  a  Sun-3/110  should  be  aware  of  the  impact  of  plane  groups  on  pre-3.2  applications. 
You  cannot  successfully  run  pre-3.2  applications  under  overview  if  overview  itself  is  running  in  the  color 
buffer.  If  you  start  overview  so  that  it  is  not  running  in  the  overlay  plane,  then  the  enable  plane  is  not  be 
properly  set  up  for  viewing  the  application.  This  means  that  you  cannot  run  overview  with  the  ~Wf  or 
-Wb  generic  tool  arguments.  Also,  you  cannot  ran  overview  on  a  desktop  created  by  sunview  using  the  - 
8bit_color_only  option. 
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NAME 

pack,  peat,  unpack  ~  compress  and  expand  files 
SYNOPSIS 

pack  [  -  ]  [  -f  ]  filename. . . 
peat  filename. . . 
unpack  filename... 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

pack  attempts  to  store  the  specified  files  in  a  packed  form  using  Huffman  (minimum  redundancy)  codes  on 
a  byte-by-byte  basis.  Wherever  possible  (and  useful),  each  input  file  filename  is  replaced  by  a  packed  file 
filename .z  with  the  same  access  modes,  access  and  modified  dates,  and  owner  as  those  of  filename.  If 
pack  is  successful,  will  be  removed. 

Packed  files  can  be  restored  to  their  original  form  using  unpack  or  peat. 

The  amount  of  compression  obtained  depends  on  the  size  of  the  input  file  and  the  frequency  distribution  of 
its  characters. 

Because  a  decoding  tree  forms  the  first  part  of  each  .z  file,  it  is  usually  not  worthwhile  to  pack  files  smaller 
than  three  blocks  unless  the  distribution  of  characters  is  very  skewed.  This  may  occur  with  printer  plots  or 
pictures. 

Typically,  large  text-files  are  reduced  to  60-75%  of  their  original  size.  Load  modules,  which  use  a  larger 
character  set  and  have  a  more  uniform  distribution  of  characters,  show  little  compression.  Their  packed 
versions  come  in  at  about  90%  of  the  original  size. 

No  packing  will  occur  if: 

the  file  appears  to  be  already  packed 

the  file  name  has  more  than  12  characters 

the  file  has  links 

the  file  is  a  directory 

the  file  cannot  be  opened 

no  disk  storage  blocks  will  be  saved  by  packing 

a  file  called  name,!,  already  exists 

the  .z  file  cannot  be  created 

an  I/O  error  occurred  during  processing 

The  last  segment  of  the  filename  must  contain  no  more  than  12  characters  to  allow  space  for  the  appended 
.z  extension.  Directories  cannot  be  packed. 

peat  does  for  packed  files  what  cat(lV)  does  for  ordinary  files,  except  that  peat  cannot  be  used  as  a  filter. 
The  specified  files  are  unpacked  and  written  to  the  standard  output.  To  view  a  packed  file  named  name  a. 
use: 

peat  filename,! 

or  just: 

peat  filename 

To  make  an  unpacked  copy  without  destroying  the  packed  version,  use 
peat  filename  >  newname 
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Failure  may  occur  if: 

the  filename  (exclusive  of  the  .z)  has  more  than  12  characters;  v  J 

the  file  cannot  be  opened; 

the  file  does  not  appear  to  be  the  output  of  pack. 

unpack  expands  files  created  by  pack.  For  each  filename  specified  in  the  command,  a  search  is  made 
for  a  file  called  filename  .z  (or  just  filename,  if  filename  ends  in  .z).  If  this  file  appears  to  be  a  packed,  it  is 
replaced  by  its  expanded  version.  The  new  file  has  the  .z  suffix  stripped  from  its  name,  and  has  the  same 
access  modes,  access  and  modification  dates,  and  owner  as  those  of  the  packed  file.  Failure  may  occur  for 
the  same  reasons  that  it  may  in  peat,  as  well  as  for  the  following: 

•  a  file  with  the  “unpacked”  name  already  exists 

•  the  unpacked  file  cannot  be  created. 

OPTIONS 

-  Print  compression  statistics  for  the  following  filename  or  names  on  the  standard  output.  Subse¬ 
quent  ‘-’s  between  filenames  toggle  statistics  off  and  on. 

-f  Force  packing  of  filename.  This  is  useful  for  causing  an  entire  directory  to  be  packed,  even  if 
some  of  the  files  will  not  benefit. 

DIAGNOSTICS 

pack  returns  the  number  of  files  that  it  failed  to  compress, 
peat  returns  the  number  of  files  it  was  unable  to  unpack, 
unpack  returns  the  number  of  files  it  was  unable  to  unpack. 

SEE  ALSO 

cat(lV) 

_ J 
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NAME 

pagesize  -  display  the  size  of  a  page  of  memory 

SYNOPSIS 

pagesize 

DESCRIPTION 

pagesize  prints  the  size  of  a  page  of  memory  in  bytes,  as  returned  by  getpagesize(2).  This  program  is  use¬ 
ful  in  constructing  portable  shell  scripts. 

SEE  ALSO 

getpagesize(2) 
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NAME 

passwd,  chfn,  chsh  -  change  local  or  NIS  password  information 
SYNOPSIS 

passwd  [  -I  I  -y  ]  [  -afs  ]  [  -d  [  username  ]  ]  [  -e  username  ]  [  -F  filename  ][~n  numdays  username  ] 

[  —X  numdays  username  ]  [  username  ] 

chfn  [  -1  I  -y  ]  [  -f  ]  [  -F  filename  ]  [  username  ] 

chsh  [  -I  1  -y  ]  [  -s  ]  [  -F  filename  ]  [  username  ] 

DESCRIPTION 

passwd  changes  (or  installs)  a  password,  login  shell  (-s  option),  or  full  name  (-f  option)  associated  with 
the  user  username  (your  own  by  default),  chsh  is  equivalent  to  passwd  with  the  -s  option,  and  chfn  is 
equivalent  to  passwd  with'  the  -f  option. 

Use  'passwd  -y’  or  yppasswd(l)  to  change  your  password  in  the  Network  Information  Service  (NIS). 
This  will  not  affect  your  local  password,  or  your  password  on  any  remote  machines  on  which  you  have 
accounts,  passwd  calls  yppasswd  automatically  if  you  do  not  have  an  entry  in  the  local  passwd  file,  and 
the  -I  option  is  not  specified. 

When  changing  a  password,  passwd  prompts  for  the  old  password  and  then  for  the  new  one.  You  must 
supply  both,  and  the  new  password  must  be  typed  twice  to  forestall  mistakes. 

If  password  aging  is  enabled,  the  first  time  an  ordinary  user  enters  the  new  password  passwd  checks  to  see 
if  the  old  password  has  “aged”  sufficiently.  Password  “aging”  is  the  amount  of  time  (usually  a  certain 
number  of  days)  that  must  elapse  between  password  changes.  If  “aging”  is  insufficient  the  new  password 
is  rejected  and  passwd  terminates. 

New  passwords  should  be  at  least  five  characters  long,  if  they  combine  upper-case  and  lower-case  letters, 
or  at  least  six  characters  long  if  in  monocase.  Users  that  persist  in  entering  shorter  passwords  are 
compromising  their  own  security.  The  number  of  significant  characters  in  a  password  is  eight,  although 
longer  passwords  will  be  accepted. 

Only  the  owner  of  the  name  or  the  super-user  may  change  a  password;  the  owner  must  prove  he  knows  the 
old  password.  The  super-user  can  change  any  password  and  is  not  forced  to  comply  with  password  aging 
requirements. 

When  changing  a  login  shell,  passwd  displays  the  current  login  shell  and  then  prompts  for  the  new  one. 
The  new  login  shell  must  be  one  of  the  approved  shells  listed  in  /etc/shells  unless  you  are  the  super-user. 
If  /etc/shells  does  not  exist,  the  only  shells  that  may  be  specified  are  /bin/sh  and  /bin/csh. 

The  super-user  may  change  anyone’s  login  shell;  normal  users  may  only  change  their  own  login  shell. 

When  changing  a  full  name,  passwd  displays  the  current  full  name,  enclosed  between  brackets,  and 
prompts  for  a  new  full  name.  If  you  type  a  RETURN,  the  full  name  is  not  changed.  If  the  full  name  is  to  be 
made  blank,  you  must  type  the  word  “none”. 

The  super-user  may  change  anyone’s  full  name;  normal  users  may  only  change  their  own. 

OPTIONS 

~a  Display  the  name  and  aging  information  for  all  users.  Can  only  be  invoked  by  the  super-user. 

-f  Change  the  full  name. 

-I  Change  the  local  password,  login  shell,  or  full  name.  If  username  exists  in  the  local  passwd  file, 
this  is  the  default. 

s  Change  the  login  shell. 

—y  Change  passwd,  login  shell,  or  full  name  in  the  NIS  database. 

-d  [username] 

Display  the  name  and  aging  information  for  the  caller  or  the  user  specified  if  the  invoker  has  the 
right  privileges. 
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~e  username 

Expire  the  password  for  the  user  name  specified.  Can  only  be  invoked  by  the  super-user. 

-F  filename 

Troax  filename  as  the  password  file. 

-n  numdays  username 

Set  the  maturity  time  of  the  password  for  username.  Passwords  that  have  not  “aged”  enough  can¬ 
not  be  changed.  Can  only  be  set  by  the  super-user. 

-X  numdays  username 

Set  the  expiration  time  of  the  password  for  username.  Can  only  be  set  by  the  super-user. 

FILES 

/etc/passwd  file  containing  all  of  this  information 

/etc/shells  list  of  approved  shells 

SEE  ALSO 

finger(l),  login(l),  yppasswd(l),  crypt(3),  passwd(5) 

NOTES 

Password  algorithms  do  not  work  with  8-bit  characters.  This  maintains  consistency  with  login  file  naming 
rules,  which  do  not  allow  8-bit  characters  in  login  names.  See  login(l)  for  explanations  about  why  login  is 
not  8-bit  clean. 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed. 
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NAME 

paste  -  join  corresponding  lines  of  several  files,  or  subsequent  lines  of  one  file 
SYNOPSIS 

paste  filenamel  filename2  . . . 
paste  -dlist  filenamel  filename!  . . . 
paste  ”S  [  -d/ijf  ]  filename 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

In  the  first  two  forms,  paste  concatenates  corresponding  lines  of  the  given  input  files  filenamel ,  filename! , 
etc.  It  treats  each  file  as  a  column  or  columns  of  a  table  and  pastes  them  together  horizontally  (parallel 
merging).  It  is  the  counterpart  of  cat(lV)  which  concatenates  vertically,  that  is,  one  file  after  the  other.  In 
the  last  form  above,  paste  replaces  the  function  of  an  older  command  with  the  same  name  by  combining 
subsequent  lines  of  the  input  file  (serial  merging).  In  all  cases,  lines  are  glued  together  with  the  TAB  char¬ 
acter,  or  with  characters  from  an  optionally  specified  list,  paste  can  be  used  as  a  filter,  if  -  is  used  in  place 
of  a  filename. 

OPTIONS 

-d  Without  this  option,  the  NEWLINE  characters  of  each  but  the  last  file  (or  last  line  in  case  of  the  -s 
option)  are  replaced  by  a  TAB  character.  This  option  allows  replacing  the  TAB  character  by  one 
or  more  alternate  characters  in  list.  The  list  is  used  circularly;  when  exhausted,  it  is  reused.  In 
parallel  merging  (no  -s  option),  the  lines  from  the  last  file  are  always  terminated  with  a  NEWLINE 
character,  not  from  the  list,  list  may  contain  the  special  escape  sequences:  \n  (NEWLINE),  \t 
(tab),  W  (backslash),  and  \0  (empty  string,  not  a  null  character).  Quoting  may  be  necessary,  if 
characters  have  special  meaning  to  the  shell. 

-s  Merge  subsequent  lines  rather  than  one  from  each  input  file.  Use  TAB  for  concatenation,  unless 
list  is  specified  with  -d.  Regardless  of  the  list,  the  very  last  character  of  the  file  is  forced  to  be  a 
NEWLINE. 

EXAMPLES 

List  directory  in  four  columns: 

Is  I  paste - 

Combine  pairs  of  lines  into  lines: 

paste  -s  -d"\t\n”  filename 

SEE  ALSO 

cat(lV),  cut(lV),  grep(l  V),  pr(lV) 

DIAGNOSTICS 

line  too  long 

Output  lines  are  restricted  to  51 1  characters, 
too  many  files 

Except  for  -s  option,  no  more  than  12  input  files  may  be  specified. 
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NAME 

pax  -  portable  archive  exchange 
SYNOPSIS 

/usr/Sbin/pax  [  -cimopuvy  ]  [  -{archive  [  -s  replstr  ]  [  -i  device  ]  [ pattern . . .  ] 

/usr/5bin/pax -r  [  -cimnopuvy  ]  [  -{archive  ]  [  -s  replstr  ]  [  -t  device  ]  [ pattern  . . .  ] 

/usr/5bin/pax  -w  [  -adimuvy  ]  [  -b  blocking  ]  [  -f  archive  ]  [  -s  replstr  J  [  -t  device  J  [  -x  format  ] 

[ pathname ...  ] 

/usr/5bin/pax  ~rw  [  -ilmopuvy  ]  [  -s  replstr  ]  [  pathname  . . .  ]  directory 
AVAILABILITY 

pax  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  informa¬ 
tion  on  how  to  install  optional  software. 

DESCRIPTION 

pax  reads  and  writes  archive  files  which  conform  to  the  Archive/Interchange  File  Format  specified  in 
IEEE  Std.  1003, 1 '■1988  (POSDC.l).  pax  can  also  read,  but  not  write,  a  number  of  other  file  formats  in  addi¬ 
tion  to  those  specified  in  the  Archive/Interchange  File  Format  description.  Support  for  these  traditional 
file  formats,  such  as  V7  tar(l)  and  System  V  binary  cpio(l)  format  archives,  is  provided  for  backward 
compatibility  and  to  maximize  portability. 

pax  will  also  support  traditional  cpio  and  System  V  tar  interfaces  if  invoked  with  the  name  cpio  or  tar 
respectively.  See  the  paxcpio(l  V)  or  ustar(lV)  manual  pages  for  more  details. 

directory  specifies  the  destination  directory  pathname  for  copies  when  both  the  -r  and  -w  options  are 
specified.  The  directory  must  exist  and  be  writable  before  the  copy  or  and  error  results. 

pathname  is  a  file  whose  contents  are  used  instead  of  the  files  named  on  the  standard  input.  When  a  direc¬ 
tory  is  named,  all  of  its  files  and  (recursively)  subdirectories  are  copied  as  well. 

A  pattern  is  given  in  the  standard  shell  pattern  matching  notation.  The  default  if  no  pattern  is  specified  is 
which  selects  all  files. 

Combinations  of  the  -r  and  -w  command  line  arguments  specify  whether  pax  will  read,  write  or  list  the 
contents  of  the  specified  archive,  or  move  the  specified  files  to  another  directory. 

If  neither  the  -r  or  -w  options  are  given,  pax  will  list  the  contents  of  the  specified  archive.  In  this  mode, 
pax  lists  normal  files  one  per  line,  hard  link  pathnames  as 

pathname  ==  linkname 

and  symbolic  link  pathnames  (if  supported  by  the  implementation)  as 
pathname  ->  linkname 

where  pathname  is  the  name  of  the  file  being  extracted,  and  linkname  is  the  name  of  a  file  which  appeared 
earlier  in  the  archive. 

If  the  -v  option  is  specified,  then  pax  list  normal  pathnames  in  the  same  format  used  by  Is(lV)  with  the  ~l 
option.  Hard  links  are  shown  as 

<ls  -I  listing>  ==  linkname 

and  symbolic  links  (if  supported)  are  shown  as 

<ls  -I  listing>  ->  linkname 

pax  is  capable  of  reading  and  writing  archives  which  span  multiple  physical  volumes.  Upon  detecting  an 
end  of  medium  on  an  archive  which  is  not  yet  completed,  pax  will  prompt  the  user  for  the  next  volume  of 
the  archive  and  will  allow  the  user  to  specify  the  location  of  the  next  volume. 

When  writing  to  an  archive,  the  standard  input  is  used  as  a  list  of  pathnames  if  no  pathname  operands  are 
specified.  The  format  is  one  pathname  per  line.  Otherwise,  the  standard  input  is  the  archive  file,  which  is 
formatted  according  to  one  of  the  specifications  in  Archive/Interchange  File  format  in  POSDC.l,  or  some 
other  implementation-defined  format. 
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The  user  ID  and  group  ID  of  the  process,  together  with  the  appropriate  privileges,  affect  the  ability  of  pax 

to  restore  ownership  and  permissions  attributes  of  the  archived  files.  See  format-reading  utility  in 

Archive/Interchange  File  Format  in  POSIX.l . 

OPTIONS 

-w  Write  the  files  and  directories  specified  by  pathname  to  the  standard  output  together  with  the  path¬ 
name  and  status  information  prescribed  by  the  archive  format  used,  pathname  refers  to  the  files 
and  (recursively)  subdirectories  of  that  directory.  If  pathname  is  not  specified,  then  the  standard 
input  is  read  to  get  a  list  of  pathnames  to  copy,  one  pathname  per  line.  In  this  case,  only  those 
pathnames  appearing  on  the  standard  input  are  copied. 

-r  Read  an  archive  file  from  the  standard  input.  Only  files  with  names  that  match  pattern  are 
selected  for  extraction.  The  selected  files  are  conditionally  created  and  copied  relative  to  the 
current  directory  tree,  subject  to  the  options  described  below.  By  default,  the  owner  and  group  of 
selected  files  will  be  that  of  the  invoking  process,  and  the  permissions  and  modification  times  will 
be  the  sames  as  those  in  the  archive. 

The  supported  archive  formats  are  automatically  detected  on  input.  The  default  output  format  is 
ustar,  but  may  be  overridden  by  the  -x  format  option  described  below. 

-rw  Read  the  files  and  directories  named  in  pathname  and  copy  them  to  the  destination  directory,  A 
directory  pathname  refers  to  the  files  and  (recursively)  subdirectories  of  that  directory.  If  path¬ 
name  is  not  specified,  the  standard  input  is  read  to  get  a  list  of  pathnames  to  copy,  one  pathname 
per  line.  In  this  case,  only  those  pathnames  appearing  on  the  standard  input  are  copied.  The 
directory  named  by  directory  must  exist  and  have  the  proper  permissions  before  the  copy  can 
occur. 

-a  Append  the  files  specified  by  pathname  to  the  specified  archive. 

-c  Complement  the  match  sense  of  pattern. 

-d  Intermediate  directories  not  explicitly  listed  in  the  archive  are  not  created.  This  option  is  ignored 
unless  the  -r  option  is  specified. 

-i  Interactively  rename  files.  Substitutions  specified  by  the  -s  option  (described  below)  are  per¬ 
formed  before  requesting  the  new  file  name  from  the  user.  A  file  is  skipped  if  an  empty  line  is 
entered  and  pax  exits  with  an  exit  status  of  0  if  an  EOF  is  encountered. 

-1  Link  files  rather  than  copy  when  possible. 

-m  File  modification  times  are  not  retained. 

-n  When  -r  is  specified,  but  “W  is  not,  the  pattern  arguments  are  treated  as  ordinary  file  names. 
Only  the  first  occurrence  of  each  of  these  files  in  the  input  archive  is  read.  The  pax  utility  exits 
with  a  zero  exit  status  after  all  files  in  the  list  have  been  read.  If  one  or  more  files  in  the  list  is  not 
found,  pax  writes  a  diagnostic  to  standard  error  for  each  of  the  files  and  exits  with  a  non-zero  exit 
status.  The  file  names  are  compared  before  any  of  the  -i,  -s,  or  -y  options  are  applied. 

-o  Restore  file  ownership  as  specified  in  the  archive.  The  invoking  process  must  have  appropriate 
privileges  to  accomplish  this. 

-p  Preserve  the  access  time  of  the  input  files  after  they  have  been  copied. 

-u  Copy  each  file  only  if  it  is  newer  than  a  pre-existing  file  with  the  same  name.  This  implies  the  -a 

option. 

-V  List  file  names  as  they  are  encountered.  Produces  a  verbose  table  of  contents  listing  on  the  stan¬ 
dard  output  when  both  the  -r  and  -w  options  are  omitted,  otherwise  the  file  names  are  printed  to 
standard  error  as  they  are  encountered  in  the  archive. 
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-y  Interactively  prompt  for  the  disposition  of  each  file.  Substitutions  specified  by  -s  options 
(described  above)  are  performed  beftn-e  prompting  the  user  for  disposition,  pax  exits  after  receiv¬ 
ing  an  EOF  or  an  input  line  starting  with  the  character  q.  Files  are  ignored  if  an  input  line  starting 
with  anything  other  than  y  is  specified.  This  option  cannot  be  used  in  conjunction  with  the  — i 
option. 

-b  blocking 

Block  the  output  at  blocking  bytes  per  write  to  the  archive  file.  A  k  suffix  multiplies  blocking  by 
1024,  a  b  suffix  multiplies  blocking  by  512  and  a  m  suffix  multiplies  blocking  by  1048576  (1 
megabyte).  If  not  specified,  blocking  is  automatically  determined  on  input  and  is  ignored  if  the 
-rw  option  is  specified. 

-f  archive 

Specify  the  pathname  of  the  input  or  output  archive,  overriding  the  default  of  the  standard  input 
for  the  ~r  option  or  the  standard  output  for  the  -w  option. 

-s  replstr 

File  names  are  modified  according  to  the  substitution  expression  using  the  syntax  of  ed(l)  as 
shown: 

“S  /old/new/[gp] 

Any  non-null  character  may  be  used  as  a  delimiter  (a  V’  is  used  here  as  an  example).  Multiple  -s 
expressions  may  be  specified;  the  expressions  are  applied  in  the  order  specified,  terminating  with 
the  first  successful  substitution.  The  optional  trailing  g  replaces  the  old  expression  each  time  it 
occurs  in  the  source  string.  The  optional  trailing  p  lists  successful  mappings  on  the  standard  error. 
Files  that  substitute  to  an  empty  string  are  ignored  both  on  input  and  output. 

-t  device 

The  device  option  argument  is  an  implementation-defined  identifier  that  names  the  input  or  output 
archive  device,  overriding  the  default  of  the  standard  input  for  -r  and  the  standard  output  for  -w. 

-X  format 

Specifies  the  output  aichivQ  format .  The  input  format,  which  must  be  one  of  the  following,  is 
automatically  determined  when  the  -r  option  is  used.  The  supported  formats  are: 

cpio  The  extended  CPIO  interchange  format  specified  in  Extended  CPIO  Format  in 
POSIX.l. 

tar  The  extended  TAR  interchange  format  specified  in  Extended  TAR  Format  in  POSIX.l. 
This  is  the  default  archive  format. 

Only  the  last  of  multiple  -f  or  -t  options  lake  effect. 

The  options  -a,  -c,  -d,  -i,  -1,  -p,  -t,  -u,  and  -y  are  provided  for  functional  compatibility  with  the  histori¬ 
cal  cpio  and  tar  utilities.  The  option  defaults  were  chosen  based  on  the  most  common  usage  of  these 
options,  therefore,  some  of  the  options  have  meanings  different  than  those  of  the  historical  commands. 

EXAMPLES 

The  following  command: 

pax  -w  -f  /dev/rmtO . 

copies  the  contents  of  the  current  directory  to  tape  drive  0. 

The  commands: 

mkdir  newdir 
cd  olddir 
pax  -rw .  newdir 

copies  the  contents  of  olddir  to  newdir. 
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The  command: 

pax -r  -s  ’,//*usr//*,,’  ~f  pax.out 

reads  the  archive  pax.out  with  all  files  rooted  in  /usr  in  the  archive  extracted  relative  to  the  current  direc¬ 
tory. 

FILES 

/dev/tty  used  to  prompt  the  user  for  information  when  the  -i  or  -y  options  are  specified 

SEE  ALSO 

cpio(l),  ed(l),  find(l),  Is(lV),  paxcpio(lV),  tar(l),  ustar(lV),  cpio(5),  tar(5) 
lEEEStd.  1003.1-1988 
DIAGNOSTICS 

pax  will  terminate  immediately,  without  processing  any  additional  files  on  the  command  line  or  in  the 
archive. 

EXIT  CODES 

pax  exits  with  one  of  the  following  values: 

0  All  files  in  the  archive  were  processed  successfully. 

>0  pax  aborted  due  to  errors  encountered  during  operation. 

BUGS 

Special  permissions  may  be  required  to  copy  or  extract  special  files. 

For  device,  user  ID,  and  group  ID  numbers  larger  than  65535  additional  header  records  are  output.  These 
records  are  ignored  by  some  historical  version  of  cpio(l)  and  tar(l). 

The  archive  formats  described  in  Archive/Interchange  File  Format  have  certain  restrictions  that  have 
been  carried  over  from  historical  usage.  For  example,  there  are  restrictions  on  the  length  of  pathnames 
stored  in  the  archive. 

When  getting  an  ‘Is  -1’  style  listing  on  tar  format  archives,  link  counts  are  listed  as  zero  since  the  ustar 
archive  format  does  not  keep  link  count  information. 

AUTHOR 

Mark  H.  Colburn 
NAPS  International 
1 17  Mackubin  Street,  Suite  1 
St.  Paul,  MN  55102 

Sponsored  by  The  USENIX  Association  for  public  distribution. 
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NAME 

paxcpio  -  copy  file  archives  in  and  out 
SYNOPSIS 

/usr/Sbin/paxcpio  -o  [  aBcv  ] 

/usr/Sbin/paxcpio  -i  [  Bcdfmrtuv  ]  [  pattern ...  ] 

/usr/Sbin/paxcpio  -p  [  adlmruv  ]  directory 

AVAILABILITY 

paxcpio  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

paxcpio  produces  and  reads  files  in  the  format  specified  by  the  cpio  Archive/Interchange  File  Format 
specified  in  IEEE  Std.  1003.1-1988. 

When  specified  with  the  -i  argument,  paxcpio  extracts  files  from  the  standard  input,  which  is  assumed  to 
be  the  product  of  a  previous  ‘paxcpio  -o'.  Only  files  with  names  that  match  pattern  are  selected,  pattern 
is  a  simple  regular  expression  given  in  the  name-generating  notation  of  the  shell  Multiple  patterns  may  be 
specified,  and  if  no  pattern  is  specified,  the  default  is  selecting  all  files.  The  extracted  files  are  condi¬ 
tionally  created  and  copied  into  the  current  directory,  and  possibly  any  levels  below,  based  upon  the 
options  specified.  The  permissions  of  the  files  will  be  those  of  the  previous  ‘paxcpio  -o’.  The  owner  and 
group  of  the  files  will  be  that  of  the  current  user  unless  the  user  has  appropriate  privileges,  in  which  case 
paxcpio  retains  the  owner  and  group  of  the  files  of  the  previous  ‘paxcpio  -o’. 

When  specified  with  the  -p  argument,  paxcpio  reads  the  standard  input  to  obtain  a  list  of  files  that  are  con¬ 
ditionally  created  and  copied  into  the  destination  directory  based  upon  the  options  described  below. 

If  an  error  is  detected,  the  cause  is  reported  and  paxcpio  continues  to  copy  other  files,  paxcpio  will  skip 
over  any  unrecognized  files  that  it  encounters  in  the  archive. 

The  following  restrictions  apply  to  paxcpio: 

•  Pathnames  are  restricted  to  256  characters. 

•  Appropriate  privileges  are  required  to  copy  special  files. 

•  Blocks  are  reported  in  5 12-byte  quantities. 

OPTIONS 

-a  Reset  access  times  of  input  files  after  they  have  been  copied.  When  the  -I  option  is  also  specified, 
the  linked  files  do  not  have  their  access  times  reset.  Can  only  be  used  with  the  -i  or  -o  argu¬ 
ments. 

-B  Input/output  is  to  be  blocked  5120  bytes  to  the  record.  Can  only  be  used  with  the  -i  or  -o  argu¬ 
ments  for  data  that  is  directed  to  or  from  character  special  files. 

-c  Write  header  information  in  ASCII  character  for  for  portability.  Can  only  be  used  with  the  -i  or 
-o  arguments.  Note:  this  option  should  always  be  used  to  write  portable  files. 

-d  Create  directories  as  needed.  Can  only  be  used  with  the  -i  or  -p  arguments. 

-f  Copy  in  all  files  except  those  in  patterns.  Can  only  be  used  with  the  ~i  argument. 

-1  Whenever  possible,  link  files  rather  than  copying  them.  Can  only  be  used  with  the -p  argument. 

-m  Retain  previous  modification  times.  This  option  is  ineffective  on  directories  that  are  being  copied. 

Can  only  be  used  with  the  -i  or  -p  arguments. 

-r  Interactively  rename  files.  The  user  is  asked  whether  lo  rename  pattern  each  invocation.  Read 
and  write  permissions  for  /dev/tty  are  required  for  this  option.  If  the  user  types  a  null  line,  the  file 
is  skipped.  Should  only  be  used  with  the  -i  or  -o  arguments. 

-t  Print  a  table  of  contents  of  the  input.  No  files  are  created.  Can  only  be  used  with  the  ~i  argument. 
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“U  Copy  files  unconditionally;  usually  an  older  file  will  not  replace  a  new  file  with  the  same  name. 
Can  only  be  used  with  the  -i  or  -p  arguments. 

“V  Verbose.  Print  the  names  of  the  affected  files.  Can  only  be  used  with  the  -i  argument.  Provides  a 
detailed  listing  when  used  with  the  -t  option. 

EXAMPLES 

The  following  command: 

Is  I  paxcpio  -o  > .  ./newfile 

copies  out  the  files  listed  by  ls(l  V)  and  redirects  them  to  the  file  newfile. 

The  following  command: 

cat  newfile  |  paxcpio  -id  "memo/al”  ”memo/b*" 

uses  the  output  file  newfile  from  paxcpio  -o,  lakes  those  files  that  match  the  patterns  "memo/al”  and 
”memo/b*",  creates  the  directories  below  the  current  directory,  and  places  the  files  in  the  appropriate 
directories. 

The  command: 

find .  -depth  -print  |  paxcpio  -pdlmv  newdir 

takes  the  file  names  piped  to  it  from  find(l)  and  copies  or  links  those  files  to  another  directory  named 
newdir,  while  retaining  the  modification  time. 

EXIT  CODES 

paxcpio  exits  with  one  of  the  following  values: 

0  All  input  files  were  copied. 

2  paxcpio  encountered  errors  in  copying  or  accessing  files  or  directories.  An  error  will  be  reported 
for  nonexistent  files  or  directories,  or  permissions  that  do  not  allow  the  user  to  access  the  source  or 
target  files. 

FILES 

/dev/tty  used  to  prompt  the  user  for  information  when  the  -i  or  -r  options  are  specified 

SEE  ALSO 

cpio(l),  find(l),  pax(lV),  tar(l),  ustar(lV),  cpio(5),  tar(5) 

IEEE  Std.  1003.1-1988 

NOTES 

It  is  important  to  use  the  -depth  option  of  find(l)  to  generate  pathnames  for  paxcpio.  This  eliminates 
problems  paxcpio  could  have  trying  to  create  files  under  read-only  directories. 

AUTHOR 

Maik  H.  Colburn 
NAPS  International 
117  Mackubin  Street,  Suite  1 
St.  Paul,  MN  55102 

Sponsored  by  The  USENIX  Association  for  public  distribution. 
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NAME 

perfmeter  -  display  system  performance  values  in  a  meter  or  strip  chart 
SYNOPSIS 

perfmeter  [  — s  sample-time  ]  [  — h  h-hand-int  ]  [  — m  m-hand-int  ]  [  —M  smax  minmax  maxmax  ] 

[  -V  value  ]  [  hostname  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User's  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

perfmeter  is  a  SunView  utility  that  displays  performance  values  (statistics)  for  a  given  hostname.  If  no 
host  is  specified,  statistics  on  the  current  host  are  metered.  The  rstatd(8C)  daemon  must  be  running  on  the 
machine  being  metered. 

When  open,  perfmeter  displays  a  performance  value  in  the  form  of  a  strip  chart.  When  closed,  it  displays 
a  meter  dial.  By  default,  the  display  is  updated  with  a  sample-time  of  2  seconds.  The  hour  hand  of  the 
meter  represents  the  average  over  a  20-second  interval;  the  minute  hand,  the  average  over  2  seconds.  The 
default  value  displayed  is  the  percent  of  CPU  being  utilized. 

The  maximum  scale  value  for  the  strip  chart  will  automatically  double  or  halve  to  accommodate  increasing 
or  decreasing  values  for  the  host  machine.  This  scale  can  be  restricted  to  a  certain  range  with  the  -M 
option. 

OPTIONS 

-s  sample-time 

Set  the  sample  time  to  sample-time  seconds. 

-h  h-hand-int 

Set  the  hour-hand  interval  to  h-hand-int  seconds. 

-m  m-hand-int 

Set  the  minute  hand  interval  to  m-hand-int  seconds. 

-M  smax  minmax  maxmax 

Set  a  range  of  maximum  values  for  the  strip  chart  Values  for  each  of  the  arguments  should  be 
powers  of  2.  smax  sets  the  starting  maximum-value,  minmax  sets  the  lowest  allowed  maximum- 
value  for  the  scale,  maxmax  sets  the  highest  allowed  maximum-value. 

—V  value 

Set  the  performance  value  to  be  monitored  to  one  of: 

cpu  Percent  of  CPU  being  utilized. 

pkts  Ethernet  packets  per  second. 

page  Paging  activity  in  pages  per  second. 

swap  Jobs  swapped  per  second. 

intr  Number  of  device  interrupts  per  second. 

disk  Disk  traffic  in  transfers  per  second. 

cntxt  Number  of  context  switches  per  second. 

load  Average  number  of  runnable  processes  over  the  last  minute. 

colls  Collisions  per  second  detected  on  the  ethemet. 

errs  Errors  per  second  on  receiving  packets. 
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USAGE 

Commands 

You  can  change  the  statistic  being  displayed  by  clicking  the  RIGHT  mouse  button,  and  then  choosing  the 
desired  menu  item.  The  other  meter  parameters  can  be  modified  by  moving  the  pointer  onto  the  tool  (either 
open  or  closed),  and  typing: 

m  Decrease  minutehandintv  by  one 

M  Increase  minutehandintv  by  one 

h  Decrease  hourhandintv  by  one 

H  Increase  hourhandintv  by  one 

1-9  Set  sampletime  to  a  range  from  1  to  9  seconds. 

FILES 

/etc/inetd.conf  starts  statistics  server 

SEE  ALSO 

sunview(l),  netstat(8C),  rstatd(8C),  vmstat(8) 
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NAME 

pg  -  page  through  a  file  on  a  soft-copy  terminal 
SYNOPSIS 

/usr/Sbin/pg  [  -cefns  ]  [  -number  ]  [  -p  string  ]  [  -k-linenumber  ]  [  +fpatternl  ]  [  filename  . . .  ] 
AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

pg  is  a  filter  that  allows  you  to  page  through  filename ,  one  screenful  at  a  time,  on  a  soft-copy  terminal. 
With  a  filename  of  or  no  filename  specified,  pg  reads  from  the  standard  input.  Each  screenful  is  fol¬ 
lowed  by  a  prompt.  If  the  user  types  a  RETURN,  another  page  is  displayed;  other  possibilities  are 
enumerated  below. 

This  command  is  different  from  previous  paginators  in  that  it  allows  you  to  back  up  and  review  something 
that  has  already  passed.  The  method  for  doing  this  is  explained  below. 

In  order  to  determine  terminal  attributes,  pg  scans  the  terminfo(5V)  data  base  for  the  terminal  type 
specified  by  the  environment  variable  TERM.  If  TERM  is  not  defined,  the  terminal  type  dumb  is  assumed. 

The  responses  that  may  be  typed  when  pg  pauses  can  be  divided  into  three  categories:  those  causing  further 
perusal,  those  that  search,  and  those  that  modify  the  perusal  environment. 

Commands  which  cause  further  perusal  normally  take  a  preceding  address,  an  optionally  signed  number 
indicating  the  point  from  which  further  text  should  be  displayed.  This  address  is  interpreted  in  either  pages 
or  lines  depending  on  the  command.  A  signed  address  specifies  a  point  relative  to  the  current  page  or  line, 
and  an  unsigned  address  specifies  an  address  relative  to  the  beginning  of  the  file.  Each  command  has  a 
default  address  that  is  used  if  none  is  provided. 

The  perusal  commands  and  their  defaults  are  as  follows: 

(+1)  NEWLINE  or  SPACE 

Display  one  page.  The  address  is  specified  in  pages. 

(+1)  I  With  a  relative  address  pg  will  simulate  scrolling  the  screen,  forward  or  backward,  the  number  of 
lines  specified.  With  an  absolute  address  this  command  prints  a  screenful  beginning  at  the 
specified  line. 

(+l)dor*D 

Simulate  scrolling  half  a  screen  forward  or  backward. 

The  following  perusal  commands  take  no  address. 

,  or  "L  Redisplay  the  current  page  of  text. 

$  Display  the  last  full  window  in  the  file.  Use  with  caution  when  the  input  is  a  pipe. 

The  following  commands  are  available  for  searching  for  text  patterns  in  the  text.  The  regular  expressions 
described  in  ed(l)  are  available.  They  must  always  be  terminated  by  a  NEWLINE,  even  if  the  -n  option  is 
specified. 

ifpatternf 

Search  forward  for  the  ith  (default  i=l)  occurrence  of  pattern.  Searching  begins  immediately 
after  the  current  page  and  continues  to  the  end  of  the  current  file,  without  wrap-around. 

r pattern" 
i*l patter nl 

Search  backwards  for  the  ith  (default  i=l)  occurrence  of  pattern.  Searching  begins  immediately 
before  the  current  page  and  continues  to  the  beginning  of  the  current  file,  without  wrap-around. 
The  *  notation  is  useful  for  Adds  100  terminals  which  will  not  properly  handle  the  ?. 
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After  searching,  pg  will  normally  display  the  line  found  at  the  top  of  the  screen.  This  can  be  modified  by 
appending  m  or  b  to  the  search  command  to  leave  the  line  found  in  the  middle  or  at  the  bottom  of  the  win¬ 
dow  from  now  on.  The  suffix  t  can  be  used  to  restore  the  original  situation. 

The  user  of  pg  can  modify  the  environment  of  perusal  with  the  following  commands: 

***  Begin  perusing  the  ith  next  file  in  the  command  line.  The  i  is  an  unsigned  numl^r, 

default  value  is  1. 

^’P  Begin  perusing  the  fth  previous  file  in  the  command  line,  i  is  an  unsigned  number, 

default  is  1. 

*  w  Display  another  window  of  text  If  i  is  present  set  the  window  size  to  /. 

s  filename  Save  the  input  in  the  named  file.  Only  the  current  file  being  perused  is  saved.  The  white 

space  between  the  s  and  filename  is  optional.  This  command  must  always  be  terminated 
by  a  NEWLINE,  even  if  the  -n  option  is  specified. 

h  Help  by  displaying  an  abbreviated  summary  of  available  commands. 

qorQ  Quitpg. 

Icommand  command  is  passed  to  the  shell,  whose  name  is  taken  from  the  SHELL  environment  vari¬ 
able.  If  this  is  not  available,  the  default  shell  is  used.  This  command  must  always  be 
terminated  by  a  NEWLINE,  even  if  the  -n  option  is  specified. 

At  any  time  when  output  is  being  sent  to  the  terminal,  the  user  can  hit  the  quit  key,  normally  CTRLA  or  the 
BREAK  (interrupt)  key.  This  causes  pg  to  stop  sending  output,  and  display  the  prompt.  The  user  may  then 
enter  one  of  the  above  commands  in  the  normal  manner.  Unfortunately,  some  output  is  lost  when  this  is 
done,  due  to  the  fact  that  any  characters  waiting  in  the  terminal’s  output  queue  are  flushed  when  the  quit 
signal  occurs. 

If  the  standard  output  is  not  a  terminal,  then  pg  acts  just  like  cat(l  V),  except  that  a  header  is  printed  before 
each  file  (if  there  is  more  than  one). 

OPTIONS 

The  command  line  options  are: 

-number  An  integer  specifying  the  size  (in  lines)  of  the  window  that  pg  is  to  use  instead  of  the 

default.  (On  a  terminal  containing  24  lines,  the  default  window  size  is  23). 

“p  string  Use  string  as  the  prompt.  If  the  prompt  string  contains  a  ‘%d’,  the  first  occurrence  of 

‘%d’  in  the  prompt  will  be  replaced  by  the  current  page  number  when  the  prompt  is 
issued.  The  default  prompt  string  is 

-c  Home  the  cursor  and  clear  the  screen  before  displaying  each  page.  This  option  is 

ignored  if  clear_screen  is  not  defined  for  this  terminal  type  in  the  terminfo(5V)  data 
base. 

-e  Do  not  pause  at  the  end  of  each  file. 

-f  Inhibit  pg  from  splitting  lines.  Normally,  pg  splits  lines  longer  than  the  screen  width, 

but  some  sequences  of  characters  in  the  text  being  displayed  (for  instance,  escape 
sequences  for  underlining)  generate  undesirable  results. 

~n  Automatic  end  of  command  as  soon  as  a  command  letter  is  entered.  Normally,  com¬ 

mands  must  be  terminated  by  a  NEWLINE  character. 

-s  Print  all  messages  and  prompts  in  standout  mode  (usually  inverse  video). 

+linenumber  Start  up  at  linenumber. 
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+fpatternf  Start  up  at  the  first  line  containing  the  regular  expression  pattern. 

EXAMPLES 

A  sample  usage  of  pg  in  reading  system  news  would  be 
news  j  pg  -p  ’(Page  %d):’ 

PILES 

/usr/share/lib/terminfo/*  terminal  information  data  base 
/tmp/pg*  temporary  file  when  input  is  firom  a  pipe 

SEE  ALSO 

cat(lV),  crypt(l),  ed(l),  grep(lV),  moreCI),  terminfo(5V) 

BUGS 

If  terminal  TAB  characters  are  not  set  every  eight  positions,  undesirable  results  may  occur. 

When  using  pg  as  a  filter  with  another  command  that  changes  the  terminal  I/O  options  (for  instance, 
crypt(l)),  terminal  settings  may  not  be  restored  correctly. 

NOTES 

While  waiting  for  terminal  input,  pg  responds  to  BREAK  ,  DEL  ,  and  "  by  terminating  execution.  Between 
prompts,  however,  these  signals  interrupt  pg’s  current  task  and  place  the  user  in  prompt  mode.  These 
should  be  used  with  caution  when  input  is  being  read  from  a  pipe,  since  an  interrupt  is  likely  to  terminate 
the  other  commands  in  the  pipeline. 

Users  of  more(l)  will  find  that  the  z  and  f  commands  are  available,  and  that  the  terminal  T,  or  *?’ 
may  be  omitted  from  the  searching  commands. 
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NAME 

plot,  aedplot,  bgplot,  crtplot,  dumbplot,  gigiplot,  hpplot,  implot,  t300,  t300s,  t40l3,  t450,  tek  -  graphics 
filters  for  various  plotters 

SYNOPSIS 

plot  [  -T terminal  ] 

AVAILABILITY 

This  command  is  available  with  the  Graphics  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

plot  reads  plotting  instructions  (see  plot(5))  from  the  standard  input  and  produces  plotting  instructions  suit¬ 
able  for  a  particular  terminal  on  the  standard  output 

If  no  terminal  is  specified,  the  environment  variable  TERM  is  used.  The  default  terminal  is  tek. 
ENVIRONMENT 

Except  for  ver,  the  following  terminal-types  can  be  used  with  ‘Ipr  -g’  see  Ipr(l))  to  produce  plotted  out¬ 
put: 

2648  1 2648a  I  h8  I  hp2648  i  hp2648a 

Hewlett  Packard  2648  graphics  terminal. 

300  DASI 300  or  GSI  terminal  (Diablo  mechanism), 

300s  1 300S  DASI  300s  terminal  (Diablo  mechanism). 

450  DASI  Hyterm  450  terminal  (Diablo  mechanism). 

4013  Tektronix  4013  storage  scope. 

4014  I  tek  Tektronix  4014  and  4015  storage  scope  with  Enhanced  Graphics  Module.  (Use 

4013  for  Tektronix  4014  or  4015  without  the  Enhanced  Graphics  Module). 

aed  AED  512  color  graphics  terminal. 

bgplot  I  bitgraph 

BBN  bitgraph  graphics  terminal. 

crt  Any  crt  terminal  capable  of  running  vi(l). 

dumb  I  un  I  unknown 

Dumb  terminals  without  cursor  addressing  or  line  printers, 
gigi  I  vtl25  DEC  vtl25  terminal. 
h7 1  hp7  I  hp7221 

Hewlett  Packard  7221  graphics  terminal, 
implot  Imagen  plotter, 

var  Benson  Varian  printer-plotter 

ver  Versatec  D 1200 A  printer-plotter.  The  output  is  scan-converted  and  suitable  input 

to  ‘Ipr-v*. 


FILES 

/usr/bin/t300 

/usr/bin/t300s 

/usr/bin/t4013 

/usr/bin/t450 

/usr/bin/aedplot 

/usr/bin/crtplot 

/usr/bin/gigiplot 

/usr/bin/implot 
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/usr/bin/plot 

/usr/bin/bgplot 

/usr/bin/dumbplot 

/usr/bin/hpplot 

/usr/bin/vplot 

/usr/bin/tek 

/usr/bin/t450 

/usr/biii/t300 

/usr/biii/t300s 

/usr/bin/vplot 

/var/tmp/vplotnwi/in« 

SEE  ALSO 

graph(lG),  Ipr(l),  vi(l),  plot(3X),  plot(5),  rasterfile(5) 
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NAME 

pr  -  prepare  file(s)  for  printing,  perhaps  in  multiple  columns 
SYNOPSIS 

pr  [  -I  +  n  ]  [ -fmt  ]  [  -h  string  ]  [  -1«  ]  [  -sc  ]  [  -wn  ]  [filename  ] . . . 

SYSTEM  V  SYNOPSIS 

/usr/5bin/pr  [-\+n][  -adfmprt  ]  [  ~eck  ]  [  -h  string  ]  [  -kk  ][-ln][  -nek  ][~on][-sc][  -wn  ] 
[filename  ] . . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
io  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

pr  prepares  one  or  more,  filenames  for  printing.  By  default,  the  output  is  separated  into  pages  headed  by  a 
date,  the  name  of  the  file,  and  the  page  number,  pr  prints  its  standard  input  if  them  are  no  filename  argu¬ 
ments.  FORMFEED  characters  in  the  input  files  cause  page  breaks  in  the  output,  as  expected. 

By  default,  columns  are  of  equal  width,  separated  by  at  least  one  SPACE;  lines  that  do  not  fit  are  truncated. 
If  the  -s  option  is  used,  lines  are  not  truncated  and  columns  are  separated  by  the  separation  character. 

Inter-terminal  messages  using  write (1)  are  forbidden  during  a  pr, 

OPTIONS 

Options  apply  to  all  following  filenames  but  may  be  reset  hQtwtQn  filenames: 

-f  Use  FORMFEED  characters  instead  of  NEWLINE  characters  to  separate  pages.  A  FORMFEED  is 
assumed  to  use  up  two  blank  lines  at  the  top  of  a  page.  Thus  this  option  does  not  affect  the  effec¬ 
tive  page  length. 

-m  Print  all  filenames  simultaneously,  each  in  one  column,  for  example: 


Print 

Print 

The 

the 

the 

third 

lines 

lines 

file’s 

of 

of 

lines 

file 

file 

go 

one. 

two. 

here. 

-t  Do  not  print  the  5-line  header  or  the  5-line  trailer  normally  supplied  for  each  page.  Pages  are  not 
separated  when  this  option  is  used,  even  if  the  ~f  option  was  used.  The  -t  option  is  intended  for 
applications  where  the  results  should  be  directed  to  a  file  for  further  processing. 

-h  string 

Use  strings  instead  of  the  file  name,  in  the  page  header. 

-\n  Take  the  length  of  the  page  to  be  n  lines  instead  of  the  default  66. 

-sc  Separate  columns  by  the  single  character  c  instead  of  by  the  appropriate  amount  of  white  space. 

A  missing  c  is  taken  to  be  a  TAB. 

-wn  For  multicolumn  output,  take  the  width  of  the  page  to  be  n  characters  instead  of  the  default  72. 

-n  Produce  n -column  output.  For  example: 


Print 

of 

in 

the 

one 

three 

lines 

file 

columns. 

Columns  are  not  balanced;  if,  for  example,  there  are  as  many  lines  in  the  file  as  there  are  lines  on 
the  page,  only  one  column  will  be  printed.  Even  if  the  -t  option  (see  below)  is  specified,  blank 
lines  will  be  printed  at  the  end  of  the  output  to  pad  it  to  a  full  page. 

+/i  Begin  printing  with  page  n . 
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When  the  -n  option  is  specified  for  multicolumn  output,  columns  are  balanced.  For  example,  if  there  are  as 
many  lines  in  the  file  as  there  are  lines  to  be  printed,  and  two  columns  are  to  be  printed,  each  column  will 
contain  half  the  lines  of  the  file.  If  the  -t  option  is  specified,  no  blank  lines  will  be  printed  to  pad  the  last 
page. 

The  options  -e  and  -i  are  assumed  for  multicolumn  output.  The  -m  option  overrides  the  -k  and  -a 
options. 

The  -f  option  does  not  assume  that  FORMFEED  uses  up  two  blank  lines;  blank  lines  will  be  printed  after 
the  FORMFEED  if  necessary.  If  the  standard  output  is  a  terminal,  -f  will  cause  pr  to  wait  for  a  RETURN 
before  printing  the  first  page. 

-a  When  combined  with  the  -n  option,  print  multicolumn  output  across  the  page.  For 
example: 

Print  the  lines 

of  one  file 

in  three  columns. 

-d  Double-space  the  output. 

-p  Pause  before  beginning  each  page  if  the  output  is  directed  to  a  terminal  (pr  will  ring  the 
bell  at  the  terminal  and  wait  for  a  RETURN). 

-r  Do  Not  print  diagnostic  reports  if  a  file  cannot  be  opened,  or  if  it  is  empty. 

-ecifc  Expand  input  TAB  characters  to  character  positions  k+l,  2*k+l,  3*^+1,  etc.  If  is  0  or 
is  omitted,  default  TAB  settings  at  every  eighth  position  are  assumed.  TAB  characters  in 
the  input  are  expanded  into  the  appropriate  number  of  SPACE  characters.  If  c  (any  non¬ 
digit  character)  is  given,  it  is  ireat^  as  the  input  TAB  character  (default  for  c  is  the  TAB 
character). 

~\ck  In  output  y  replace  white  space  wherever  possible  by  inserting  TAB  characters  to  character 
positions  it+1,  3*/:+!,  etc.  If  /:  is  0  or  is  omitted,  default  TAB  settings  at  every 

eighth  position  are  assumed.  If  c  (any  non-digit  character)  is  given,  it  is  treated  as  the 
output  TAB  (default  for  c  is  the  TAB  character). 

-ncJt  Provide  Jt -digit  line  numbering  (default  for  k  is  5).  The  number  occupies  the  first  ^+1 
character  positions  of  each  column  of  normal  output  or  each  line  of -m  output  If  c  (any 
non-digit  character)  is  given,  it  is  appended  to  the  line  number  to  separate  it  from  what¬ 
ever  follows  (default  for  c  is  a  TAB). 

-ok  Offset  each  line  by  k  character  positions.  The  number  of  character  positions  per  line  is 
the  sum  of  the  width  and  offset. 


EXAMPLES 

Print  a  file  called  dreadnought  on  the  printer  —  this  is  the  simplest  use  of  pr: 

example  %  pr  dreadnought  |  Ipr 
example  % 

Produce  three  laminations  of  a  file  called  ridings  side  by  side  in  the  output,  with  no  headers  or  trailers,  the 
results  to  appear  in  the  file  called  Yorkshire: 

example  %  pr  -m  -t  ridings  ridings  ridings  >  Yorkshire 
example  % 

FILES 

/dev/tty*  to  suspend  messages. 

SEE  ALSO 

cat(lV),  Ipr(l),  write(l) 
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can’t  print  0  cols,  using  1 

-0  was  specified  as  a  -n  option, 
pr:  bad  key  key 

An  illegal  option  was  given. 

pr;  No  room  for  columns. 

The  number  of  columns  requested  will  not  fit  on  the  page, 
pr;  Too  many  args 

More  than  10  files  were  specified  with  the  -m  option. 
filename  ;  error 

filename  could  not  be  opened.  This  diagnostic  is  not  printed  if  pr  is  printing  on  a  terminal. 
SYSTEM  V  DIAGNOSTICS 
pr:  bad  option 

An  illegal  option  was  given. 

pr;  width  too  small 

The  number  of  columns  requested  will  not  fit  on  the  page, 
pr;  too  many  files 

More  than  10  files  were  specified  with  tlie  -m  option, 
pr;  page-buffer  overflow 

The  formatting  required  is  more  complicated  than  pr  can  handle, 
pr:  out  of  space 

pr  could  not  allocate  a  buffer  it  required, 
pt:  filename  empty  file 

filename  was  empty.  This  diagnostic  is  printed  after  all  the  files  are  printed  if  pr  is  printing  on  a 
terminal. 

pr:  can’t  open  filename 

filename  could  not  be  opened.  This  diagnostic  is  printed  after  aU  the  files  are  printed  if  pr  is  print¬ 
ing  on  a  terminal. 

BUGS 

The  options  described  above  interact  with  each  other  in  strange  and  as  yet  to  be  defined  ways. 
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NAME 

printenv  -  display  environment  variables  currently  set 

SYNOPSIS 

printenv  [  variable  ] 

DESCRIPTION 

printenv  prints  out  the  values  of  the  variables  in  the  environment.  If  a  variable  is  specified,  only  its  value 
is  printed. 

SEE  ALSO 

csh(l),  sh(l),  stty(lV),  tset(l),  environ(5V) 

DIAGNOSTICS 

If  a  variable  is  specified  and  it  is  not  defined  in  the  environment,  printenv  returns  an  exit  status  of  1. 
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NAME 

prof  -  display  profile  data 
SYNOPSIS 

prof  [  -alnsz  ]  [  -v  -low  [  -high  ]  ]  [  image-file  [  profile-file  . . .  ]  ] 

DESCRIPTION 

prof  produces  an  execution  profile  of  a  program.  The  profile  date  is  taken  from  the  profile  file  which  is 
created  by  programs  compiled  with  the  -p  option  of  cc(lV)  and  other  compilers.  That  option  also  links  in 
versions  of  tiie  library  routines  (see  monitor(3))  which  are  compiled  for  profiling.  The  symbol  table  in  the 
executable  image  file  image-file  (a.out  by  default)  is  read  and  correlated  with  the  profile  file  profile-file 
(mon.out  by  default).  For  each  external  symbol,  the  percentage  of  time  spent  executing  between  that  sym¬ 
bol  and  the  next  is  printed  (in  decreasing  order),  together  with  the  number  of  times  that  routine  was  called 
and  the  number  of  milliseconds  per  call.  If  more  than  one  profile  file  is  specified,  the  prof  output  shows 
the  sum  of  the  profile  information  in  the  given  profile  files. 

To  telly  the  number  of  calls  to  a  routine,  the  modules  that  make  up  the  program  must  be  compiled  with  the 
’cc  -p’  option  (see  cc(lV)).  This  option  also  means  that  the  profile  file  is  produced  automatically. 

A  single  function  may  be  split  into  subfunctions  for  profiling  by  means  of  the  MARK  macro  (see  prof(3)). 
Beware  of  quantization  errors. 

The  profiled  program  must  call  exit(2V)  or  return  normally  for  the  profiling  information  to  be  saved  in  the 
mon.out  file. 

OPTIONS 

-a  Report  all  symbols  rather  than  just  external  symbols. 

“1  Sort  the  output  by  symbol  value. 

-n  Sort  the  output  by  number  of  calls. 

-s  Produce  a  summary  profile  file  in  mon.sum.  This  is  really  only  useful  when  more  than  one  profile 
file  is  specified. 

-z  Display  routines  which  have  zero  usage  (as  indicated  by  call  counts  and  accumulated  time). 

-V  [  -low  [  -high  ]] 

Suppress  all  printing  and  produce  a  graphic  version  of  the  profile  on  the  standard  output  for 
display  by  the  plot(lG)  filters.  When  plotting,  the  numbers  low  and  high,  (by  default  0  and  100), 
select  a  percentage  of  the  profile  to  be  plotted,  with  accordingly  higher  resolution. 

ENVIRONMENT 

PROFDIR 

If  this  environment  variable  contains  a  value,  place  profiling  output  within  that  directory,  in  a  file 
named  pid.programname.  pid  is  the  process  ID,  and  programname  is  the  name  of  the  program 
being  profiled,  as  determined  by  removing  any  path  prefix  from  the  argvfO]  with  which  the  pro¬ 
gram  was  called.  If  the  variable  contains  a  NULL  value,  no  profiling  output  is  produced.  Other¬ 
wise,  profiling  output  is  placed  in  the  file  mon.out. 

FILES 

a*out  executable  file  containing  namelist 

%V'^0¥X3ilRlpid,programname 
mon.out  profiling  output 

mon.sum  summary  profile 

SEE  ALSO 

cc(lV),  gprof(l),  plot(lG),  tcov(l),  exit(2V),  profil(2),  monitor(3) 
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BUGS 

prof  is  confused  by  the  FORTRAN  compiler  which  puts  the  entry  points  at  the  bottom  of  subroutines  and 
functions. 
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NAME 

ps  ~  display  the  status  of  current  processes 


SYNOPSIS 

ps  [  HacCegjklnrSuUvwx  ]  [  -tx  ]  I  [  n«w  ]  [  kernel-name  ]  [  c-dump-file  ]  [  swap-file  ] 

DESCRIPTION 

ps  displays  information  about  processes.  Normally,  only  those  processes  that  are  running  with  your  effec¬ 
tive  user  ID  and  are  attached  to  a  controlling  terminal  (see  termio(4))  are  shown.  Additional  categories  of 
processes  can  be  added  to  the  display  using  various  options.  In  particular,  the  -a  option  allows  you  to 
include  processes  that  are  not  owned  by  you  (that  do  not  have  your  user  ID),  and  the  -x  option  allows  you 
to  include  processes  without  control  terminals.  When  you  specify  both  -a  and  -x,  you  get  processes 
owned  by  anyone,  with  or  without  a  control  terminal.  The  -r  option  restricts  the  list  of  processes  printed  to 
“running”  processes:  runnable  processes,  those  in  page  wait,  or  those  in  short-term  non-intemiptible  waits. 

ps  displays  the  process  ID,  under  PID;  the  control  terminal  (if  any),  under  TT;  the  cpu  time  used  by  the  pro¬ 
cess  so  far.  including  both  user  and  system  time),  under  TIME;  the  state  of  the  process,  under  STAT;  and 
finally,  an  indication  of  the  COMMAND  that  is  running. 


The  state  is  given  by  a  sequence  of  four  letters,  for  example,  ‘RWNA*. 


First  letter 


Second  letter 


Third  letter 


Fourth  letter 


indicates  the  runnability  of  the  process; 

R  Runnable  processes. 

T  Stopped  processes. 

P  Processes  in  page  wait. 

D  Processes  in  non-intemiptible  waits;  typically  short-term  waits  for  disk  or  NFS 
VO. 

S  Processes  sleeping  for  less  than  about  20  seconds. 

I  Processes  that  are  idle  (sleeping  longer  than  about  20  seconds). 

Z  Processes  that  have  terminated  and  that  are  waiting  for  their  parent  process  to 
io  a  wait(2V)  (“zombie”  processes). 

indicates  whether  a  process  is  swapped  out; 

blank  Represented  as  a  SPACE  character,  in  this  position  indicates  that  the  process  is 
loaded  (in  memory). 

W  Process  is  swapped  out 

>  Process  has  specified  a  soft  limit  on  memory  requirements  and  has  exceeded 
that  limit;  such  a  process  is  (necessarily)  not  swapped. 

indicates  whether  a  process  is  running  with  altered  CPU  scheduling  priority  (nice(l)): 
blank  Represented  as  a  SPACE  character,  in  this  position  indicates  that  the  process  is 
running  without  special  treatment. 

N  The  process  priority  is  reduced, 

<  The  process  priority  has  been  raised  artificially, 

indicates  any  special  treatment  of  the  process  for  virtual  memory  replacement.  The 
letters  correspond  to  options  to  the  vadvise(2)  system  call.  Currently  the  possibilities 
are: 

blank  Represented  as  a  SPACE  character,  in  this  position  stands  for  VA^NORM. 

A  Stands  for  VA^ANOM.  An  A  typically  represents  a  program  which  is  doing 
garbage  collection. 

S  Stands  for  VA_SEQL.  An  S  is  typical  of  large  image  processing  programs  that 

are  using  virtual  memory  to  sequentially  address  voluminous  data. 


kernel-name  specifies  the  location  of  the  system  namelist.  If  the  -k  option  is  given,  c-dump-file  tells  ps 
where  to  look  for  the  core  dump.  Otherwise,  the  core  dump  is  located  in  the  file  /vmcore  and  this  argu¬ 
ment  is  ignored,  swap-file  gives  the  location  of  a  swap  file  other  than  the  default,  /dev/drum. 
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OPTIONS 

Options  must  all  be  combined  to  form  the  first  argument. 

-a  Include  information  about  processes  owned  by  others. 

-c  Display  the  command  name,  as  stored  internally  in  the  system  for  accounting  purposes,  rather  than 
the  command  arguments,  which  are  kept  in  the  process  address  space.  This  is  more  reliable,  if  less 
informative,  as  the  process  is  free  to  destroy  the  latter  information. 

-C  Display  raw  CPU  time  instead  of  the  decaying  average  in  the  %CPU  field. 

-e  Display  the  environment  as  well  as  the  arguments  to  the  command. 

-g  Display  all  processes.  Without  this  option,  ps  prints  only  “interesting”  processes.  Processes  are 
deemed  to  be  uninteresting  if  they  are  process  group  leaders.  This  normally  eliminates  topdevel 
command  interpreters  and  processes  waiting  for  users  to  login  on  free  terminals. 

-j  Display  a  listing  useful  for  job  control  information,  with  fields  PPID,  PID,  PGID,  SID,  TT,  TPGID, 
ST  AT,  UID,  TIME,  and  COMMAND  as  described  below. 

With  this  option,  the  STAT  field  has  three  additional  letters: 

C  indicates  the  process  does  not  want  SIGCHLD  when  a  child  changes  state  done  to  job  con¬ 
trol. 

E  The  process  has  completed  an  exec,  and  the  parent  can  no  longer  change  the  process  group 
of  this  process, 

O  The  process  is  an  orphan,  with  no  parent  process  to  handle  job  control  signals, 

-k  Normally,  kernel-name  defaults  to  /vmunix,  c-dump-file  is  ignored,  and  swap-file  defaults  to 
/dev/drum.  With  the  -k  option  in  effect,  these  arguments  default  to  /vmunix,  /vmcore,  and 
/dev/drum,  respectively. 

-I  Display  a  long  listing,  with  fields  F,  PPID,  CP,  PRI,  NI,  SZ,  RSS,  and  WCHAN,  as  described  below. 

-n  Produce  numeric  output  for  some  fields.  In  a  long  listing,  the  WCHAN  field  is  printed  numerically 

rather  than  symbolic^ly,  or,  in  a  user  listing,  the  USER  field  is  replaced  by  a  UID  field, 

-r  Restrict  output  to  “running”  processes. 

-S  Display  accumulated  CPU  time  used  by  this  process  and  all  of  its  reaped  children. 

-u  Display  user-oriented  output.  This  includes  fields  USER,  %CPU,  %MEM,  SZ,  RSS  and  START  as 
described  below. 

-U  Update  a  private  database  where  ps  keeps  system  information.  Include  ‘ps  -U’  in  the  /etc/rc  file. 

-V  Display  a  version  of  the  output  describing  virtual  memory  information.  This  includes  fields  RE,  SL, 
PAGEIN,  SIZE,  RSS,  LIM,  %CPU  and  %MEM,  described  below. 

-w  Use  a  wide  output  format  (132  columns  rather  than  80);  if  repeated,  that  is,  -ww,  use  arbitrarily  wide 
output.  This  information  is  used  to  decide  how  much  of  long  commands  to  print 

-X  Include  processes  with  no  controlling  terminal. 

The  following  two  options  are  mutually  exclusive.  When  specified,  these  options  must  appear  immediately 
following  the  last  option. 

-tx  Restrict  output  to  processes  whose  controlling  terminal  is  x  (which  should  be  specified  as  printed 
by  ps;  for  example,  t3  for  /dev/tty3,  tco  for  /dev/console,  tdO  for  /dev/ttydO,  t?  for  processes 
with  no  terminal,  etc).  This  option  must  be  the  last  one  given. 

num  A  process  number  may  be  given,  in  which  case  the  output  is  restricted  to  that  process.  This  option 
must  also  be  last,  and  must  appear  with  no  white  space  between  it  and  the  previous  option. 
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DISPLAY  FORMATS 

Fields  that  are  not  common  to  all  output  formats: 

USER  Name  of  the  owner  of  the  process. 

%CPU  CPU  use  of  the  process;  this  is  a  decaying  average  over  up  to  a  minute  of  previous  (real) 
time.  Because  the  time  base  over  which  this  is  computed  varies  (since  processes  may  be 
very  young)  it  is  possible  for  the  sum  of  all  %CPU  fields  to  exceed  100%. 

NI  Process  scheduling  increment  (see  getpriority(2)  and  nice(3V)). 

SIZE 

SZ  The  combined  size  of  the  data  and  stack  segments  (in  kilobytes) 

RSS  Real  memory  (resident  set)  size  of  the  process  (in  kilobytes). 

LIM  Soft  limit  on  memory  used,  specified  using  a  call  to  getrliinit(2);  if  no  limit  has  been 

specified,  this  is  shown  as  xx. 

%MEM  Percentage  of  real  memory  used  by  this  process. 

RE  Residency  time  of  the  process  (seconds  in  core). 

SL  Sleep  time  of  the  process  (seconds  blocked). 

PAGEIN  Number  of  disk  I/Os  resulting  fi'om  references  by  the  process  to  pages  not  loaded  in  core. 

UID  Numeric  user-ID  of  process  owner. 

PPID  Numeric  ID  of  parent  of  process. 

SID  Numeric  ID  of  the  session  to  which  the  process  belongs.  SID  =  PGID  =  PID  indicates  a  ses¬ 

sion  leader. 

PGID  Numeric  ID  of  the  process  group  of  the  process. 

TPGID  Numeric  ID  of  the  process  group  associated  with  the  terminal  specified  under  TT  (dis¬ 
tinguished  process  group,  see  teriiiiio(4)). 

CP  Short-term  CPU  utilization  factor  (used  in  scheduling). 

PRI  Process  priority  (non-positive  when  in  non-intemiptible  wait). 

START  Time  the  process  was  created  if  today,  or  the  date  it  was  created  if  before  today. 

WCHAN  Event  on  which  process  is  waiting  (an  address  in  the  system).  A  symbol  is  chosen  that 

classifies  the  address,  unless  numeric  output  is  requested  (see  the  n  flag).  In  this  case,  the 
address  is  printed  in  hexadecimal. 


Flags  (in  hex)  associated  with  process  as  in  <sys/proc.h>: 

SLOAD 

00000001 

in  core 

SSYS 

00000002 

swapper  or  pager  process 

SLOCK 

00000004 

process  being  swapped  out 

SSWAP 

ooomos 

save  area  flag 

STRC 

00000010 

process  is  being  traced 

SWTED 

00000020 

parent  has  been  told  that  this  process  stopped 

SULOCK 

00000040 

user  can  set  lock  in  core 

SPAGE 

00000080 

process  in  page  wait  state 

SKEEP 

00000100 

another  flag  to  prevent  swap  out 

SOMASK 

00000200 

restore  old  mask  after  taking  signal 

SWEXIT 

00000400 

working  on  exiting 

SPHYSIO 

00000800 

doing  physical  I/O 

SVFORK 

00001000 

process  resulted  from  vforkQ 

SVFDONE 

00002000 

another  vfork  flag 

SNOVM 

00004000 

no  vm,  parent  in  a  vfork() 

SPAGI 

00008000 

init  data  space  on  demand,  from  vnode 
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SSEQL 

00010000 

user  warned  of  sequential  vm  behavior 

SUANOM 

00020000 

user  warned  of  anomalous  vm  behavior 

STIMO 

00040000 

timing  out  during  sleep 

SORPHAN 

00080000 

process  is  orphaned 

STRACNG 

00100000 

process  is  tracing  another  process 

SOWEUPC 

00200000 

process  is  being  profiled  and  has  a  pending  count  increment 

SSEL 

00400000 

selecting;  wakeup/wailing  danger 

SFAVORD 

02000000 

favored  treatment  in  swapout  and  pageout 

SLKDONE 

04000000 

record-locking  has  been  done 

STRCSYS 

08000000 

tracing  system  calls 

SNOCLDSTOP 

10000000 

SIGCHLD  not  sent  when  child  stops 

SEXECED 

20000000 

process  has  completed  an  exec 

SRPC 

40000000 

sunview  window  locking 

A  process  that  has  exited  and  has  a  parent,  but  has  not  yet  been  waited  for  by  the  parent,  is  marked 
<defunct>;  a  pr(x:ess  that  is  blocked  trying  to  exit  is  marked  <exiting>;  otherwise,  ps  makes  an  educated 
guess  as  to  the  file  name  and  arguments  given  when  the  process  was  created  by  examining  memory  or  the 
swap  area. 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC^defauIt  control  the  character  classification 
throughout  ps.  On  entry  to  ps,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC^CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  “C”  locale. 


FILES 


/vmunix 

/devAimem 

/dev/drum 

/vmcore 

/dev 

/etc/psdatabase 


system  namelist 
kernel  memory 
swap  device 
core  file 

searched  to  find  swap  device  and  terminal  names 
system  namelist,  device,  and  wait  channel  information 


SEE  ALSO 

kiU(l),  w(l),  getpriority(2),  getrlimit(2),  wait(2V),  vadvise(2),  nice(3V),  termio(4),  locaIe(5),  pstat(8) 

BUGS 

Things  can  change  while  ps  is  running;  the  picture  it  gives  is  only  a  close  approximation  to  the  current 
state. 
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NAME 

ptx  “  generate  a  permuted  index 
SYNOPSIS 

ptx  [  -f  ]  [  -t  ]  [  -w  n  ]  [  -g  n  ]  [  -o  only  ]  [  -i  ignore  ]  [  -b  break]  [-t][  input  [  output  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

ptx  generates  a  permuted  index  of  the  contents  of  file  input  onto  file  output  (defaults  are  standard  input  and 
output),  ptx  has  three  phases:  the  first  does  the  permutation,  generating  one  line  for  each  keyword  in  an 
input  line.  The  keyword  is  rotated  to  the  front.  The  permuted  file  is  then  sorted.  Finally,  the  sorted  lines 
are  rotated  so  the  keyword  comes  at  the  middle  of  the  page,  ptx  produces  output  in  the  form: 

OCX  tail"  "b^ore  keyword"  "keyword  and  after"  "head** 

where  xx  may  be  an  nroff(l)  or  troff(l)  macro  for  user-defined  formatting.  The  before  keyword  and  key¬ 
word  and  after  fields  incorporate  as  much  of  the  line  as  will  fit  around  the  keyword  when  it  is  printed  at  the 
middle  of  the  page,  tail  and  head,  at  least  one  of  which  is  an  empty  string  are  wrapped-around  pieces 
small  enough  to  fit  in  the  unused  space  at  the  opposite  end  of  the  line.  When  original  text  must  be  dis¬ 
carded,  7’  marks  the  spot. 

OPTIONS 
-f 

-t 

-w  n 

-gn 

“O  only 
-i  ignore 

-b  break 

-r 


FILES 

/usr/lib/eign 

SEE  ALSO 

nroff(l),  sort(lV),  troff(l) 

BUGS 

Line  length  counts  do  not  account  for  overstriking  or  proportional  spacing. 


Fold  upper  and  lower  case  letters  for  sorting. 

Prepare  the  output  for  the  phototypesetter;  the  default  line  length  is  100  characters. 

Use  the  next  argument,  n,  as  the  width  of  the  output  line.  The  default  line  length  is  72 
characters. 

Use  the  next  argument,  k,  as  the  number  of  characters  to  allow  for  each  gap  among  the 
four  parts  of  the  line  as  finally  printed.  The  default  gap  is  3  characters. 

Use  as  keywords  only  the  words  given  in  the  only  file. 

Do  not  use  as  keywords  any  words  given  in  the  ignore  file.  If  the  -i  and  -o  options  are 
missing,  use  /usr/lib/eign  as  the  ignore  file. 

Use  the  characters  in  the  break  file  to  separate  words.  In  any  case,  TAB,  NEWLINE,  and 
SPACE  characters  are  always  used  as  break  characters. 

Take  any  leading  nonblank  characters  of  each  input  line  to  be  a  reference  identifier  (as 
to  a  page  or  chapter)  separate  from  the  text  of  the  line.  Attach  that  identifier  as  a  5th 
field  on  each  output  line. 
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NAME 

pwd  -  display  the  pathname  of  the  current  working  directory 

SYNOPSIS 

pwd 

DESCRIPTION 

pwd  prints  the  pathname  of  the  working  (current)  directory. 

If  you  are  using  csh(l),  you  can  use  the  dirs  builtin  command  to  do  the  same  job  more  quickly;  but  dirs 
can  give  a  different  answer  in  the  rare  case  that  the  current  directory  or  a  containing  directory  was  moved 
after  the  shell  descended  into  it.  This  is  because  pwd  searches  back  up  the  directory  tree  to  report  the  true 
pathname,  whereas  dirs  remembers  the  pathname  from  the  last  cd(l)  command.  The  example  below  illus¬ 
trates  the  differences. 

example  %  cd  /usr/wendy/january/reports 
example%  pwd 
/  usr/wendy/january/reports 
example%  dirs 
"/january/reports 

example  %  mv  7january  7february 
example  %  pwd 
/usr/wendy/february/reports 
example  %  dirs 
7january/reporls 
example  % 

pwd  and  dirs  also  give  different  answers  when  you  change  directory  through  a  symbolic  link.  For  exam¬ 
ple: 

example  %  cd  /usr/wendy/january/reports 
exam  pie  %  pwd 
/usr/wendy/january/reports 
example%  dirs 
7january/reports 

example  %  Is  -1  /usr/wendy/january 

Irwxrwxrwx  1  wendy  17  Jan  30  1983  /usr/wendy/january  ->  /usr/wendy/1984/jan/ 

example%  cd  /usr/wendy/january 

example  %  pwd 

/usr/wendy/1984/jan 

example%  dirs 

/usr/wendy/january 

The  pathnames  of  files  mounted  with  the  Automounter  can  also  change  if  the  file  is  not  used  for  a  certain 
time  interval  (the  default  is  five  minutes).  To  prevent  this,  set  the  environment  variable 
AUTOMOUNT_FIXNAMES.  See  automount(8)  for  more  information. 

SEE  ALSO 

cd(l),  csh(l),  automount(8) 
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NAME 

quota  -  display  a  user’s  disk  quota  and  usage 
SYNOPSIS 

quota  [  — V  ]  [  username  ] 

DESCRIPTION 

quota  displays  users’  disk  usage  and  limits.  Only  the  super-user  may  use  the  optional  username  argument 
to  view  the  limits  of  users  other  than  himself. 

quota  without  options  displays  only  warnings  about  mounted  file  systems  where  usage  is  over  quota. 
Remotely  mounted  file  systems  which  are  mounted  with  the  “noquota”  option  (see  fstab(5))  are  ignored. 

OPTIONS 

-V  Display  user’s  quotas  on  all  mounted  file  systems  where  quotas  exist. 

FILES 

quotas  quota  file  at  the  file  system  root 

/etc/mtab  list  of  currently  mounted  filesystems 

SEE  ALSO 

quotactl(2),  fstab(5),  edquota(8),  quotaon(8),  rquotad(8C) 
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NAME 

ranlib  -  convert  archives  to  random  libraries 
SYNOPSIS 

ranlib  [  -t  ]  archive. . . 

DESCRIPTION 

ranlib  converts  each  archive  to  a  form  that  can  be  linked  more  rapidly,  ranlib  does  this  by  adding  a  table 

of  contents  called _ .SYMDEF  to  the  beginning  of  the  archive,  ranlib  uses  ar(lV)  to  reconstruct  the 

archive.  Sufficient  temporary  file  space  must  be  available  in  the  file  system  that  contains  the  current  direc¬ 
tory. 

OPTIONS 

“t  ranlib  only  “touches”  the  archives  and  does  not  modify  them.  This  is  useful  after  copying  an 
archive  or  using  the  -t  option  of  make(l)  to  avoid  having  Id(l)  complain  about  an  “out  of  date” 
symbol  table. 

SEE  ALSO 

ar(lV),  ld(l),  lorder(l),  make(l) 

BUGS 

Because  generation  of  a  library  by  ar  and  randomization  of  the  library  by  ranlib  are  separate  processes, 
phase  errors  are  possible.  The  linker.  Id,  warns  when  the  modification  date  of  a  library  is  more  recent  than 
the  creation  date  of  its  dictionary;  but  this  means  that  you  get  the  warning  even  if  you  only  copy  the 
library. 
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NAME 

rasfilterStol  ~  convert  an  8-bit  deep  rasterfile  to  a  1-bit  deep  rasterfile 
SYNOPSIS 

rasfilterStol  [  -d  ]  [  -rgba  threshold  ]  [  infile  [  outfile  ]] 

DESCRIPTION 

rasfilterStol  reads  the  8-bit  deep  rasterfile  infile  (the  standard  input  default)  and  converts  it  to  the  1-bit 
deep  rasterfile  outfile  (standard  output  default)  by  thresholding  or  ordered  dither.  The  output  format  is  Sun 
standard  rasterfile  format  (see  <rasterfile.h>).  This  command  is  useful  for  viewing  8-bit  rasterfiles  on  dev¬ 
ices  that  can  only  display  monochrome  images. 

OPTIONS 

-d  Use  ordered  dither  to  convert  the  input  file  instead  of  thresholding. 

-rgba  threshold 

Set  the  threshold  for  the  red,  green,  blue,  and  average  pixel  color  values.  Pixels  whose  color 
values  are  greater  than  or  equal  to  all  of  the  thresholds  are  given  a  value  of  0  (white)  in  the  output 
rasterfile;  other  pixels  are  set  to  1  (black).  The  average  threshold  defaults  to  128,  the  individual 
thresholds  to  zero. 


EXAMPLE 

The  command 

example^  screendump  -f  /dev/cgtwo  |  rasfilterStol  |  Ipr  -Pversatec  -v 

prints  a  monochromatic  representation  of  the  /dev/cgtwo  frame  buffer  on  the  printer  named  versatec  using 
the  V  output  filter  (see  /etc/printcap).  The  printer  must  support  an  appropriate  imaging  model  such  as 
PostScript  in  order  to  print  the  image. 

FILES 

/usr/lib/rasfilters/*  filters  for  non-standard  rasterfile  formats 
SEE  ALSO 

Ipr(l),  rastrepl(l),  screendump(l),  screenload(l) 
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NAME 

rastrepl  -  magnify  a  raster  image  by  a  factor  of  two 
SYNOPSIS 

rastrepl  [  input-file  [  output-file  ]] 

DESCRIPTION 

rastrepl  reads  the  rasterfile  input-file  (the  standard  input  default)  and  converts  it  to  the  rasterfile  output-file 
(the  standard  output  default)  which  is  twice  as  large  in  width  and  height.  Pixel  replication  is  used  to  mag¬ 
nify  the  image.  The  output  file  has  the  same  type  as  the  input  file. 

EXAMPLES 

The  following  command: 

example  %  screendump  |  rastrepl  |  Ipr  -Pversatec  -v 

sends  a  rasterfile  containing  the  current  frame  buffer  contents  to  the  Versatec  plotter,  doubling  the  size  of 
the  image  so  that  it  fills  a  single  page. 

FILES 

/usr/lib/rasfilters/>t‘  filters  for  non-standard  rasterfile  formats 
SEE  ALSO 

Ipr(l),  screendump(l),  screenload(I) 
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NAME 

rep  -  remote  file  copy 
SYNOPSIS 

rep  [-p  ]filenamel  filename2 
rep  [  “pr  ]  filename . ,  .directory 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

rep  copies  files  between  machines.  Each  filename  or  directory  argument  is  either  a  remote  file  name  of  the 
form: 

hostnameipath 

or  a  local  file  name  (containing  no  characters,  or  a  7’  before  any  ‘:*s). 

If  a  filename  is  not  a  full  path  name,  it  is  interpreted  relative  to  your  home  directory  on  hostname.  A  path 
on  a  remote  host  may  be  quoted  (using  \, ",  or  ')  so  that  the  metacharacters  are  interpreted  remotely. 

rep  does  not  prompt  for  passwords;  your  current  local  user  name  must  exist  on  hostname  and  allow  remote 
command  execution  by  rsh(lC). 

rep  handles  third  party  copies,  where  neither  source  nor  target  files  are  on  the  current  machine.  Hosmames 
may  also  take  the  form 

username  ^hostname  ifilename 

to  use  username  rather  than  your  current  local  user  name  as  the  user  name  on  the  remote  host,  rep  also 
supports  Internet  domain  addressing  of  the  remote  host,  so  that: 

username  @host  .domain  '.filename 

specifies  the  username  to  be  used,  the  hostname,  and  the  domain  in  which  that  host  resides.  Filenames  that 
are  not  full  path  names  will  be  interpreted  relative  to  the  home  directory  of  the  user  named  username  y  on 
the  remote  host. 

The  destination  hostname  may  also  take  the  form  hostname. username '.filename  to  support  destination 
machines  that  are  running  older  versions  of  rep. 

OPTIONS 

-p  Attempt  to  give  each  copy  the  same  modification  times,  access  times,  and  modes  as  the  original 
file. 

-r  Copy  each  subtree  rooted  at  filename ;  in  this  case  the  destination  must  be  a  directory. 

FILES 

.eshre 

.login 

.profile 

SEE  ALSO 

ftp(lC),  rlogin(lC).  rsh(lC) 

BUGS 

rep  does  not  detect  all  cases  where  the  target  of  a  copy  might  be  a  file  in  cases  where  only  a  directory 
should  be  legal. 

rep  can  become  confused  by  output  generated  by  commands  in  a  .profile,  .eshre,  or  .login  file  on  the 
remote  host. 
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rep  requires  that  the  source  host  have  permission  to  execute  commands  on  the  remote  host  when  doing 
third-party  copies. 

If  you  forget  to  quote  metacharacters  intended  for  the  remote  host  you  get  an  incomprehensible  error  mes¬ 
sage. 


Sun  Release  4.1 


Last  change:  17  May  1989 


431 


RDIST(l) 


USER  COMMANDS 


RDIST(l) 


NAME 

rdist  ~  remote  file  distribution  program 

SYNOPSIS 

rdist  [  -b  ]  [  -h  ]  [  -i  ]  [  -n  ]  [  -q  ]  [  -R  ]  [  -V  ]  [  -w  ]  [  -y  ]  [  -d  macro  =  value  ] 

[ ”f  distfile ]  [ “in  host ] . , .  [ package ...  ] 

rdist  [-b][-h][-i][-n][-q]  [“R][-v][“W]  [-y] 

-c  pathname  . . .  [login  @]hostname[:destpath  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  See  Installing  SunOS  4.1  for 
information  about  installing  optional  software. 

DESCRIPTION 

rdist  maintains  copies  of  files  on  multiple  hosts.  It  preserves  the  owner,  group,  mode,  and  modification 
time  of  the  master  copies,  and  can  update  programs  that  are  executing.  Normally,  a  copy  on  a  remote  host 
is  updated  if  its  size  or  modification  time  differs  from  the  original  on  the  local  host,  rdist  reads  the  indi¬ 
cated  distfile  for  insU-uctions  on  updating  files  and/or  directories.  If  distfile  is  the  standard  input  is 
used.  If  no  ~f  option  is  present,  rdist  first  looks  in  its  working  directory  for  distfile,  and  then  for  Distfile, 
for  instructions. 

rdist  updates  each  package  specified  on  the  command  line;  if  none  are  given,  all  packages  are  updated 
according  to  their  entries  in  the  distfile. 

OPTIONS 

“b  Binary  comparison.  Perform  a  binary  comparison  and  update  files  if  they  differ,  rather  than 
merely  comparing  dates  and  sizes. 

-h  Follow  symbolic  links.  Copy  the  file  that  the  link  points  to  rather  than  the  link  itself. 

-i  Ignore  unresolved  links,  rdist  will  normally  try  to  maintain  the  link  structure  of  files  being 

transffered  and  warn  the  user  if  all  the  links  cannot  be  found. 

-n  Print  the  commands  without  executing  them.  This  option  is  useful  for  debugging  a  distfile, 

-q  Quiet  mode.  Do  not  display  the  files  being  updated  on  the  standard  output. 

-R  Remove  extraneous  files.  If  a  directory  is  being  updated,  remove  files  on  the  remote  host  that  do 

not  correspond  to  those  in  the  master  (local)  directory.  This  is  useful  for  maintaining  truly  identi¬ 
cal  copies  of  directories. 

-V  Verify  that  the  files  are  up  to  date  on  all  the  hosts.  Any  files  that  are  out  of  date  are  displayed,  but 
no  files  are  updated,  nor  is  any  mail  sent. 

-w  Whole  mode.  The  whole  file  name  is  appended  to  the  destination  directory  name.  Normally,  only 
the  last  component  of  a  name  is  used  when  renaming  files.  This  preserves  the  directory  structure 
of  the  files  being  copied,  instead  of  flattening  the  directory  structure.  For  instance,  renaming  a  list 
of  files  such  as  ( dirl/fl  dir2/f2  )  to  d5r3  would  create  files  dir3/dirl/fl  and  dir3/dir2/f2  instead 
of  dir3/fl  and  dir3/f2.  When  the  -w  option  is  used  with  a  filename  that  begins  with ",  everything 
except  the  home  directory  is  appended  to  the  destination  name. 

-y  Younger  mode.  Do  not  update  remote  copies  that  are  younger  than  the  master  copy,  but  issue  a 
warning  message  instead. 

-d  macro  =value 

Define  macro  to  have  value.  This  option  is  used  to  define  or  override  macro  definitions  in  the 
distfile.  value  can  be  the  empty  string,  one  name,  or  a  list  of  names  surrounded  by  parentheses 
and  separated  by  white  space. 
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-c  pathname  . . .  [login @]hostname[\destpath  ] 

Update  each  pathname  on  the  named  host.  (Relative  filenames  are  taken  as  relative  to  your  home 
directory.)  If  the  ‘ login (§>’  prefix  is  given,  the  update  is  performed  with  the  user  ID  of  login.  If 
the  'idestpath*  is  given,  the  remote  file  is  installed  as  that  pathname. 

-f  distfile 

Use  the  description  file  distfile.  A  as  the  distfile  argument  denotes  the  standard  input. 

-m  host 

Limit  which  machines  are  to  be  updated.  Multiple  -m  arguments  can  be  given  to  limit  updates  to 
a  subset  of  the  hosts  listed  in  the  distfile. 

USAGE 

Packages 

A  typical  package  begins  with  a  label  composed  of  the  package  name  followed  by  a  colon: 
package : 

This  label  allows  you  to  group  any  number  of  file-to-host  and  file-to-timestamp  mappings  into  a  single  dis¬ 
tribution  package.  If  no  package  label  appears  in  the  distfile,  the  default  package  includes  all  mappings  in 
the  file. 

A  file-to-host  mapping  specifies  a  list  of  files  or  directories  to  distribute,  their  destination  host(s),  and  any 
rdist  primitives  to  use  in  performing  tlie  update.  A  mapping  of  this  sort  takes  the  form: 

( pathname  ... )  ->  ( hostname  . . .  )  primitive  ;  [primitive  ;] . . . 

In  this  case,  each  pathname  is  the  full  pathname  of  a  local  file  or  directory  to  distribute;  each  hostname  is 
the  name  of  a  remote  host  on  which  those  files  are  to  be  copied,  and  primitive  is  one  of  the  rdist  primitive 
listed  under  Primitives^  below.  If  there  is  only  one  pathname  or  hostname,  the  surrounding  parentheses 
can  be  omitted.  A  hostname  can  also  take  the  form: 

login@hostname 

in  which  case  the  update  is  performed  as  the  user  named  login. 

A  file-to-timestamp  mapping  is  used  to  monitor  which  local  files  are  updated  with  respect  to  a  local  “times¬ 
tamp”  file.  This  mapping  takes  the  form: 

{filename  ...)::  timestamp-file  primitive  ;  [primitive  ;] . . . 

In  this  case,  timestamp-file  is  the  name  of  a  file,  the  modification  time  of  which  is  compared  with  each 
named  file  on  the  local  host.  If  a  file  is  newer  than  time-stamp-file,  rdist  displays  a  message  to  that  effect. 
If  there  is  only  one  filename,  the  parentheses  can  be  omitted. 

White  Space  Characters 

NEWLINE,  TAB,  and  SPACE  characters  are  all  treated  as  white  space;  a  mapping  continues  across  input 
lines  until  the  start  of  the  next  mapping:  either  a  single  filename  followed  by  a  *->’  or  the  opening 
parenthesis  of  a  filename  list. 

Comments 

Comments  begin  with  #  and  end  with  a  NEWLINE. 

Macros 

rdist  has  a  limited  macro  facility.  Macros  are  only  expanded  in  filename  or  hostname  lists,  and  in  the  argu¬ 
ment  lists  of  certain  primitives.  Macros  cannot  be  used  to  stand  for  primitives  or  their  options,  or  the  *->’ 
or  symbols. 

A  macro  definition  is  a  line  of  the  form: 
macro  =  value 
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A  macro  reference  is  a  string  of  the  form: 

${macro} 

although  (as  with  make(l))  the  braces  can  be  omitted  if  the  macro  name  consists  of  just  one  character. 
Metacharacters 

The  shell  meta-characters:  [,  1,  {,  },  *  and  ?  are  recognized  and  expanded  (on  the  local  host  only)  just  as 
they  are  with  csh(l).  Metacharacters  can  be  escaped  by  prepending  a  backslash. 

The  “  character  is  also  expanded  in  the  same  way  as  with  csh,  however,  it  is  expanded  separately  on  the 
local  and  destination  hosts. 

Filenames 

File  names  that  do  not  begin  with  /  or "  are  taken  to  be  relative  to  user’s  home  directory  on  each  destination 
host.  Note  that  they  are  not  relative  to  the  current  working  directory. 

Primitives 

The  following  primitives  can  be  used  to  specify  actions  rdist  is  to  take  when  updating  remote  copies  of 
each  file. 

install  [  -b  ]  [  -h  ]  [  “i  ]  [  -R  ]  [  -v  J  [  “W  ]  [  -y  ]  [newname] 

Copy  out-of-date  files  and  directories  (recursively).  If  no  install  primitive  appears  in  the  package 
entry,  or  if  no  newname  option  is  given,  the  name  of  the  local  file  is  given  to  the  remote  host’s 
copy.  If  absent  from  the  remote  host,  parent  directories  in  a  filename’s  path  are  created.  To  help 
prevent  disasters,  a  non-empty  directory  on  a  target  host  is  not  replaced  with  a  regular  file  or  a 
symbolic  link  by  rdist.  However,  when  using  the  -R  option,  a  non-empty  directory  is  removed  if 
the  corresponding  filename  is  completely  absent  on  the  master  host.  The  options  for  install  have 
the  same  semantics  as  their  command  line  counterparts,  but  are  limited  in  scope  to  a  particular 
map.  The  login  name  used  on  the  destination  host  is  the  same  as  the  local  host  unless  the  destina¬ 
tion  name  is  of  the  format  login@host.  In  that  case,  the  update  is  performed  under  the  username 
login. 

notify  address . . . 

Send  mail  to  the  indicated  TCP/IP  address  of  the  form: 
user  @  host 

that  lists  the  files  updated  and  any  errors  that  may  have  occurred.  If  an  address  does  not  contain  a  '@host  ’ 
suffix,  rdist  uses  the  name  of  the  destination  host  to  complete  the  address. 

except  filename  . . . 

Omit  from  updates  the  files  named  as  arguments. 
except_patpatfern . . . 

Omit  from  updates  the  filenames  that  match  each  regular-expression  pattern  (see  ed(l)  for  more 
information  on  regular  expressions.  Note  that  \  and  $  characters  must  be  escaped  in  the  distfile. 
Shell  variables  can  also  be  used  within  a  pattern,  however  shell  filename  expansion  is  not  sup¬ 
ported. 

special  [filename] ” command-line” 

Specify  a  Bourne  shell,  sh(l)  command  line  to  execute  on  the  remote  host  after  each  named  file  is 
updated.  If  no  filename  argument  is  present,  the  command-line  is  performed  for  every  updated 
file,  with  the  shell  variable  FILE  set  to  the  file’s  name  on  the  local  host.  The  quotation  marks 
allow  command-line  to  span  input  lines  in  the  distfile;  multiple  shell  commands  must  be  separated 
by  semicolons  (;). 

The  default  working  directory  for  the  shell  executing  each  command-line  is  the  user’s  home  direc¬ 
tory  on  the  remote  host. 
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EXAMPLES 

The  following  sample  distfile  instructs  rdist  to  maintain  identical  copies  of  a  shared  library,  a  shared- 
library  initialized  data  file,  several  include  files,  and  a  directory,  on  hosts  named  hermes  and  magus.  On 
magus,  commands  are  executed  as  root,  rdist  notifies  merlm@druid  whenever  it  discovers  that  a  local 
file  has  changed  relative  to  a  timestamp  file. 

HOSTS  =:  ( hermes  root(@)magus ) 

FILES  =  ( /usr/local/lib/libcant.so.1.1 

/  usr  local/li  b/libcantsa.  1 .1  /usr/local/include/{*  .h) 

/usr/local/bin ) 

${FILES}  ->  ${HOSTS} 
install  -R ; 

${F[LES} ::  /usr/local/lib/timestamp 
notify  merlin(§)druid ; 

FILES 

/tmp/rdist*  temporary  file  for  update  lists 

SEE  ALSO 

csh(l),  ed(l),  sh(l),  stat(2V) 

DIAGNOSTICS 

A  complaint  about  mismatch  of  rdist  version  numbers  may  really  stem  from  some  problem  with  starting 
your  shell,  for  example,  you  are  in  too  many  groups. 

BUGS 

Source  files  must  reside  or  be  mounted  on  the  local  host. 

There  is  no  easy  way  to  have  a  special  command  executed  only  once  after  all  files  in  a  directory  have  been 
updated. 

Variable  expansion  only  works  for  name  lists;  there  should  be  a  general  macro  facility, 
rdist  aborts  on  files  that  have  a  negative  modification  time  (before  Jan  1, 1970). 

There  should  be  a  “force”  option  to  allow  replacement  of  non-empty  directories  by  regular  files  or  sym- 
links.  A  means  of  updating  file  modes  and  owners  of  otherwise  identical  files  is  also  needed. 

WARNINGS 

root  does  not  have  its  accustomed  access  privileges  on  NFS  mounted  file  systems.  Using  rdist  to  copy  to 
such  a  file  system  may  fail,  or  the  copies  may  be  owned  by  user  “nobody.” 
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NAME 

refer  -  expand  and  insert  references  from  a  bibliographic  database 
SYNOPSIS 

refer  [  -ben  ]  [  -ar  ]  [  -cstring  ]  [  -kx  ]  [  filename  ]  [  -^ys  ]  filename. . . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4,1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

refer  is  a  preprocessor  for  nroff(l),  or  troff(l),  that  finds  and  formats  references.  The  input  files  (standard 
input  by  default)  are  copied  to  the  standard  output,  except  for  lines  between  and  W  command  lines. 
Such  lines  are  assumed  to  contain  keywords  as  for  lookbib(l),  and  are  replaced  by  information  from  a 
bibliographic  data  base.  The  user  can  avoid  the  search,  override  fields  from  it,  or  add  new  fields.  The 
reference  data,  from  whatever  source,  is  assigned  to  a  set  of  troff  strings.  Macro  packages  such  as  ms(7) 
print  the  finished  reference  text  from  these  strings.  A  flag  is  placed  in  the  text  at  the  point  of  reference.  By 
default,  the  references  are  indicated  by  numbers. 

When  refer  is  used  with  eqn(l),  neqn,  or  tbl(l),  refer  should  be  used  first  in  the  sequence,  to  minimize  the 
volume  of  data  passed  through  pipes. 

OPTIONS 

-b  Bare  mode  —  do  not  put  any  flags  in  text  (neither  numbers  or  labels). 

-e  Accumulate  references  instead  of  leaving  the  references  where  encountered,  until  a  sequence  of 
the  form: 

.[ 

$LIST$ 

.] 

is  encountered,  and  then  write  out  all  references  collected  so  far.  Collapse  references  to  the  same 
source. 

-n  Do  not  search  the  default  file. 

-ar  Reverse  the  first  r  author  names  (Jones,  J.  A.  instead  of  J.  A.  Jones).  If  r  is  omitted,  all  author 
names  are  reversed. 

-cstring 

Capitalize  (with  SMALL  CAPS)  the  fields  whose  key-letters  are  in  string. 

-kx  Instead  of  numbering  references,  use  labels  as  specified  in  a  reference  data  line  beginning  with  the 
characters  %x\  By  default,  x  is  L. 

~\m,n  Instead  of  numbering  references,  use  labels  from  the  senior  author’s  last  name  and  the  year  of 
publication.  Only  the  first  m  letters  of  the  last  name  and  the  last  n  digits  of  the  date  are  used.  If 
either  of  m  or  « is  omitted,  the  entire  name  or  date,  respectively,  is  used. 

-p  filename 

Take  the  next  argument  as  a  file  of  references  to  be  searched.  The  default  file  is  searched  last. 

-skeys  Sort  references  by  fields  whose  key-letters  are  in  the  keys  string,  and  permute  reference  numbers 
in  the  text  accordingly.  Using  this  option  implies  the  -e  option.  The  key-letters  in  keys  may  be 
followed  by  a  number  indicating  how  many  such  fields  are  used,  with  a  +  sign  taken  as  a  very 
large  number.  The  default  is  AD,  which  sorts  on  the  senior  author  and  date.  To  sort  on  all  authors 
and  then  the  date,  for  instance,  use  the  options  *-sA+T’. 
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FILES 

/usr/dict/papers  directory  of  default  publication  lists  and  indexes 
/usr/lib/refer  directory  of  programs 

SEE  ALSO 

addbib(l),  eqn(l),  indxbib(l),  lookbib(l),  nroff(l),  rofn)ib(l),  sortbib(l),  tbl(l),  troff(l) 
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NAME 

rev  -  reverse  the  order  of  characters  in  each  line 

SYNOPSIS 

rev  [filename  ] . . . 

DESCRIPTION 

rev  copies  the  named  files  to  the  standard  output,  reversing  the  order  of  characters  in  every  line.  If  no  file 
is  specified,  the  standard  input  is  copied. 
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NAME 

rlogin  -  remote  login 
SYNOPSIS 

rlogin  [-L]  [-8]  [  -ec  J  [  -1  username  ]  hostname 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

rlogin  establishes  a  remote  login  session  from  your  terminal  to  the  remote  machine  named  hostname. 

Hostnames  are  listed  in  the  hosts  database,  which  may  be  contained  in  the  /etc/hosts  file,  the  Network 
Information  Service  (NIS)  hosts  database,  the  Internet  domain  name  server,  or  a  combination  of  these. 
Each  host  has  one  official  name  (the  first  name  in  the  database  entry),  and  optionally  one  or  more  nick¬ 
names.  Either  official  hostnames  or  nicknames  may  be  specified  in  hostname. 

Each  remote  machine  may  have  a  file  named  /etc/hosts.equiv  containing  a  list  of  trusted  hostnames  with 
which  it  shares  usernames.  Users  with  the  same  username  on  both  the  local  and  remote  machine  may 
rlogin  from  the  machines  listed  in  the  remote  machine’s  /etc/liosts.eqiiiv  file  without  supplying  a  pass¬ 
word.  Individual  users  may  set  up  a  similar  private  equivalence  list  with  the  file  .rhosts  in  their  home 
directories.  Each  line  in  this  file  contains  two  names:  a  hostname  and  a  username  separated  by  a  SPACE. 
An  entry  in  a  remote  user’s  .rhosts  file  permits  the  user  named  username  who  is  logged  into  hostname  to 
rlogin  to  the  remote  machine  as  the  remote  user  without  supplying  a  password.  If  the  name  of  the  local 
host  is  not  found  in  the  /etc/hosts.equiv  file  on  the  remote  machine,  and  the  local  username  and  hosmame 
are  not  found  in  the  remote  user’s  .rhosts  file,  then  the  remote  machine  will  prompt  for  a  password.  Host- 
names  listed  in  /etc/hosts.equiv  and  .rhosts  files  must  be  the  official  hostnames  listed  in  the  hosts  database; 
nicknames  may  not  be  used  in  either  of  these  files. 

To  counter  security  problems,  the  .rhosts  file  must  be  owned  by  either  the  remote  user  or  by  root. 

The  remote  terminal  type  is  the  same  as  your  local  terminal  type  (as  given  in  your  environment  TERM 
variable).  The  terminal  or  window  size  is  also  copied  to  the  remote  system  if  the  server  supports  the  op¬ 
tion,  and  changes  in  size  are  reflected  as  well.  All  echoing  takes  place  at  the  remote  site,  so  that  (except  for 
delays)  the  remote  login  is  transparent.  Flow  control  using  "S  (CTRL-S)  and  "Q  (CTRL-Q)  and  flushing  of 
input  and  output  on  interrupts  are  handled  properly. 

ESCAPES 

Lines  that  you  type  which  start  with  the  tilde  character  are  “escape  sequences”  (the  escape  character  can  be 
changed  using  the  -e  options): 

,  Disconnect  from  the  remote  host  —  this  is  not  the  same  as  a  logout,  because  the  local  host  breaks 
the  connection  with  no  warning  to  the  remote  end. 

SUSP  Suspend  the  login  session  (only  if  you  are  using  the  C  shell),  susp  is  your  “suspend”  character, 
usually  *Z,  (CTRL-Z),  see  tty(l). 

"dsusp  Suspend  the  input  half  of  the  login,  but  output  will  still  be  seen  (only  if  you  are  using  the  C  shell), 
dsusp  is  your  “deferred  suspend”  character,  usually  "Y,  (CTRL-Y),  see  tty(l). 

OPTIONS 

-L  Allow  the  rlogin  session  to  be  run  in  “litout”  mode. 

-8  Pass  eight-bit  data  across  the  net  instead  of  seven-bit  data. 

-ec  Specify  a  different  escape  character,  c,  for  the  line  used  to  disconnect  from  the  remote  host. 

-I  username 

Specify  a  different  username  for  the  remote  login.  If  you  do  not  use  this  option,  the  remote  user- 
name  used  is  the  same  as  your  local  username. 
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FILES 

/usr/hosts/+  for  the  hostname  version  of  the  command 

/etc/hosts*equiv  list  of  trusted  hostnames  with  shared  usernames 

/ .rhosts  private  list  of  trusted  hostname/usemame  combinations 

SEE  ALSO 

rsh(lC),  stty(lV),  tty(l),  ypcat(l),  hosts(5),  naniied(8C) 

BUGS 

This  implementation  can  only  use  the  TCP  network  service. 

More  of  the  environment  should  be  propagated. 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed. 
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NAME 

rm,  rmdir  ~  remove  (unlink)  files  or  directories 
SYNOPSIS 

rm  [  “  ]  [  -fir  ]  filename. . . 
rmdir  directory. . . 

DESCRIPTION 

rm  removes  (directory  entries  for)  one  or  more  files.  If  an  entry  was  the  last  link  to  the  file,  the  contents  of 
that  file  are  lost.  See  In(lV)  for  more  information  about  multiple  links  to  files. 

To  remove  a  file,  you  must  have  write  permission  in  its  directory;  but  you  do  not  need  read  or  write  permis¬ 
sion  on  the  file  itself.  If  you  do  not  have  write  permission  on  the  file  and  the  standard  input  is  a  terminal, 
rm  displays  the  file  s  permissions  and  waits  for  you  to  type  in  a  response.  If  your  response  begins  with  y 
the  file  is  deleted;  otherwise  the  file  is  left  alone. 

rmdir  removes  each  named  directory,  rmdir  only  removes  empty  directories. 

OPTIONS 

-  Treat  the  following  arguments  as  filenames  so  that  you  can  specify  filenames  starting  with  a 
minus. 

-f  Force  files  to  be  removed  without  displaying  permissions,  asking  questions  or  reporting  errors. 

-i  Ask  whether  to  delete  each  file,  and,  under  -r,  whether  to  examine  each  directory.  Sometimes 

called  the  interactive  option. 

-r  Recursively  delete  the  contents  of  a  directory,  its  subdirectories,  and  the  directory  itself. 

SEE  ALSO 

lii(l  V),  su(lV) 

BUGS 

‘rm  -r’  removes  a  directory  and  its  files  only  if  your  real  user  ID  has  write  permission  on  that  directory. 
DIAGNOSTICS 

rm:  filename:  No  such  file  or  directory 

filename  does  not  exist,  rm  will  also  return  false  (1)  if  filename  was  not  found. 

WARNING 

It  is  forbidden  to  remove  the  file  *.  /  to  avoid  the  antisocial  consequences  of  inadvertently  doing  something 
like  ‘rm  ~r 
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NAME 

roffbib  -  format  and  print  a  bibliographic  database 
SYNOPSIS 

roffbib[-e]  [-h]  [-m filename]  [-n/?]  [-o/wr]  [~Q]  [~raN]  [-sN]  [-Tterm]  [-V] 

[  -X  ]  [filename  ] . . . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  in¬ 
formation  on  how  to  install  optional  software. 

DESCRIPTION 

roffbib  prints  out  all  records  in  a  bibliographic  database,  in  bibliography  format  rather  than  as  footnotes  or 
endnotes.  Generally  it  is  used  in  conjunction  with  sortbib(l): 

example  %  sortbib  database  j  roffbib 

OPTIONS 

roffbib  accepts  all  options  understood  by  nroff(l)  except  -I  and  -q. 

-e  Produce  equally-spaced  words  in  adjusted  lines  using  full  terminal  resolution. 

-h  Use  output  tabs  during  horizontal  spacing  to  speed  output  and  reduce  output  character  count.  TAB 

settings  are  assumed  to  be  every  8  nominal  character  widths. 

-m  filename 

Prepend  the  macro  file  /usr/share/lib/tmac/tmacmame  to  the  input  files.  There  should  be  a  space 
between  the  ~m  and  the  macro  filename.  This  set  of  macros  will  replace  the  ones  defined  in 
/usr/share/lib/tmac/tmac.bib. 

-np  Number  first  generated  page  p . 

-olist  Print  only  page  numbers  that  appear  in  the  comma-separated  list  of  numbers  and  ranges.  A  range 
N-M  means  pages  N  through  M\  an  initial  -N  means  firom  the  beginning  to  page  N;  a  final  N~ 
means  from  page  N  to  end. 

-Q  Queue  output  for  the  phototypesetter.  Page  offset  is  set  to  1  inch. 

-roN  Set  register  a  (one-character)  to  N.  The  command-line  argument  -rNl  will  number  the  references 
starting  at  1. 

Four  command-line  registers  control  formatting  style  of  the  bibliography,  much  like  the  number 
registers  of  ms(7).  The  flag  -rV2  will  double  space  the  bibliography,  while  -rVl  will  double 
space  references  but  single  space  annotation  paragraphs.  The  line  length  can  be  changed  from  the 
default  6.5  inches  to  6  inches  with  the  -rL6i  argument,  and  the  page  offset  can  be  set  from  the  de¬ 
fault  of  0  to  one  inch  by  specifying  -rOli  (capital  O,  not  zero). 

-sM  Halt  prior  to  every  N  pages  for  paper  loading  or  changing  (default  N  =1).  To  resume,  enter  NEW- 
LINE  or  RETURN. 

-Tterm  Specify  term  as  the  terminal  type. 

-V  Send  ouq^ut  to  the  Versatec.  Page  offset  is  set  to  1  inch.  This  option  not  available  on  Sun386i 
systems. 

-X  If  abstracts  or  comments  are  entered  following  the  %X  field  key,  roffbib  will  format  them  into 
paragraphs  for  an  annotated  bibliography.  Several  %X  fields  may  be  given  if  several  annotation 
paragraphs  are  desired. 

FILES 

/usr/share/lib/tmac/tmac.bib  file  of  macros  used  by  nrolT/troff 
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SEE  ALSO 

addbib(l),  indxbib(l)»  lookbib(l),  iiroff(l)  refer(l),  sortbib(l),  trofT(l) 
Formatting  Documents 

BUGS 

Users  have  to  rewrite  macros  to  create  customized  formats. 
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NAME 

rpcgen  -  RPC  protocol  compiler 

SYNOPSIS 

rpcgen  infile 

rpcgen  [  -liname[=value\  ]  [  -I  [  -K  seconds  ]  ]  [  -L  ]  [  -T  ]  infile 
rpcgen  -c  |  -h  |  -1  |  -m  |  -t  [  ~o  outfile  ]  [  infile  ] 
rpcgen  -s  transport  [  -o  outfile  ]  [  infile  ] 

DESCRIPTION 

rpcgen  generates  C  code  to  implement  an  RPC  protocol.  The  input  to  rpcgen  is  a  language  similar  to  C 
known  as  the  RPC  Language  (Remote  Procedure  Call  Language).  Information  about  the  syntax  of  RPC 
Language  is  available  in  the  ^rpcgen  *  Programming  Guide  in  the  Network  Programming  manual. 

rpcgen  is  normally  used  as  in  the  first  synopsis  where  it  takes  an  input  file  and  generates  four  output  files. 
If  the  infile  is  named  proto.x,  then  rpcgen  generates  a  header  file  in  proto.h,  XDR  routines  in  proto_xdr.c, 
server  side  stubs  in  proto_svc.c»  and  client  side  stubs  in  proto_clnt.c.  With  the  -T  option,  it  also  gen¬ 
erates  the  RPC  dispatch  table  in  proto_tbl.i. 

The  second  synposis  provides  special  features  which  allow  for  the  creation  of  more  sophisticated  RPC 
servers.  These  features  include  support  for  RPC  dispatch  tables,  and  user  provided  #defines.  The  entries  in 
the  RPC  dispatch  table  contain: 

•  pointers  to  the  service  routine  corresponding  to  that  procedure 

•  a  pointer  to  the  input  and  output  arguments 

•  the  size  of  these  routines 


A  server  can  use  the  dispatch  table  to  check  authorization  and  then  to  execute  the  service  routine;  a  client 
library  may  use  it  to  deal  with  the  details  of  storage  management  and  XDR  data  conversion. 

The  other  two  synopses  shown  above  are  used  when  one  does  not  want  to  generate  all  the  output  files,  but 
only  a  particular  one.  Their  usage  is  described  in  the  EXAMPLES  section  below. 

The  C-preprocessor,  cpp(l),  is  run  on  the  input  file  before  it  is  actually  interpreted  by  rpcgen,  so  all  the 
cpp  directives  are  legal  within  an  rpcgen  input  file.  For  each  type  of  output  file,  rpcgen  defines  a  special 
cpp  symbol  for  use  by  the  rpcgen  programmer: 


RPC__HDR 

RPC^XDR 

RPC_SVC 

RPC_CLNT 

RPC~TBL 


defined  when  compiling  into  header  files 
defined  when  compiling  into  XDR  routines 
defined  when  compiling  into  server  side  stubs 
defined  when  compiling  into  client  side  stubs 
defined  when  compiling  into  RPC  dispatch  tables 


In  addition,  rpcgen  does  a  little  preprocessing  of  its  own.  Any  line  beginning  with  ‘  ’  is  passed  directly 

into  the  output  file,  uninterpreted  by  rpcgen.  For  every  data  type  referred  to  in  infile,  rpcgen  assumes  that 
there  exists  a  routine  with  the  string  ‘xdr_’  prepended  to  the  data  type.  If  this  routine  does  not  exist  in  the 
RPC/XDR  library,  it  must  be  provided.  Providing  an  undefined  data  type  allows  customization  of  XDR  rou¬ 
tines. 


OPTIONS 

-c  Compile  into  XDR  routines. 

-Dname[=value] 

Define  a  symbol  name.  Equivalent  to  the  #define  directive  in  the  source.  If  no  value  is 
given,  name  is  defined  as  1.  This  option  may  be  called  more  than  once. 

”h  Compile  into  C  data-definitions  (a  header  file).  The  -T  option  can  be  used  in  conjunction  to 

produce  a  header  file  which  supports  RPC  dispatch  tables. 

“I  Compile  support  for  inetd(8C)  in  the  server  side  stubs.  Such  servers  can  be  self  started  or 

can  be  started  by  inetd.  When  the  server  is  self-started,  it  backgrounds  itself  by  default.  A 
special  define  symbol  RPC  SVC  FG  can  be  used  to  run  the  server  process  in  foreground,  or 
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alternately  the  user  may  just  compile  it  without  the  -I  option.  If  there  are  no  pending  client 
requests,  the  inetd  servers  exit  after  120  seconds  (default).  The  default  can  be  changed  with 
the  -K  option.  All  the  error  messages  for  inetd  servers  are  always  logged  in  with  sysIog(3). 

~K  seconds  If  the  server  was  started  by  inetd,  specify  the  time  in  seconds  after  which  the  server  should 
exit  if  there  is  no  further  activity.  This  option  is  useful  for  customization.  If  seconds  is  0, 
the  server  exits  after  serving  that  given  request.  If  seconds  is  -1,  the  server  hangs  around 
for  ever  after  being  started  by  inetd.  This  option  is  valid  only  with  the  -I  option. 

“1  Compile  into  client  side  stubs. 

When  the  servers  are  started  in  foreground,  use  syslog( )  to  log  the  server  errors  instead  of 
printing  them  on  the  standard  error. 


-m  Compile  into  server  side  stubs,  but  do  not  generate  a  “main”  routine.  This  option  is  useful 

for  doing  callback-routines  and  for  people  who  need  to  write  their  own  “main”  routine  to  do 
initialization.  For  inetd  support,  they  should  be  compiled  with  the  -I  option.  In  such  cases, 
it  defines  2  global  variables:  __rpcpmstart  and  _rpcfdtype.  The  value  of  _rpcpmstart 
should  be  1  or  0  depending  upon  whether  it  was  started  by  inetd  or  not.  The  value  of 
_rpcfdtype  should  be  SOCK_STREAM  or  SOCK^DGRAM  depending  upon  the  type  of  the 
connection. 


-0  ou0e  Specify  the  name  of  the  output  file.  If  none  is  specified,  the  standard  output  is  used  (~c,  -h, 
-I,  -m,  -s  and  -t  modes  only). 


-s  transport  Compile  into  server  side  stubs  for  the  given  transport.  The  supported  transports  are  udp  and 
tcp.  This  option  may  be  called  more  than  once  so  as  to  compile  a  server  that  serves  multiple 
transports.  For  inetd  support,  they  should  be  compiled  with  the  -I  option, 

-t  Compile  into  RPC  dispatch  table. 

-T  Generate  the  code  to  support  RPC  dispatch  tables. 

The  options  -c,  -h,  -1,  -m,  -s  and  -t  are  used  exclusively  to  generate  a  particular  type  of  file,  while  the 
options  “D,  ”1,  -L  and  -T  are  global  and  can  be  used  with  the  other  options. 


EXAMPLES 

The  following  example  generates  all  the  five  files:  prot.h,  prot_clnt.c,  prot_svc.c,  prot__xdr.c  and 
prot_tbl.i.  The  server  error  messages  are  logged,  instead  of  being  sent  to  the  standard  error. 

example%  rpcgen  -LT  prot.x 


The  following  example  generates  prot.h,  prot_clnt.c,  prot_xdr.c  and  prot_svc.c.  prot  svcx  supports 
server  invocation  by  inetd.  If  the  server  is  started  by  inetd,  the  server  exits  after  20  seconds  of  inactivity. 

exaniple%  rpcgen  -I  -K  20  proLx 

The  following  example  sends  the  header  file  (with  support  for  dispatch  tables)  on  the  standard  output. 
exaniple%  rpcgen  -hT  prot.x 

The  following  example  sends  the  server  side  stubs  file  for  the  transport  tcp  on  the  standard  output, 
exam  pie  %  rpcgen  -s  tcp  protx 


SEE  ALSO 

cpp(l),  rpc(3N),  inetd(8C) 

‘rpcgen*  Programming  Guide  in  Network  Programming 
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BUGS 

The  RPC  Language  does  not  support  nesting  of  structures.  As  a  work-around,  structures  can  be  declared  at 
the  top-level,  and  their  name  used  inside  other  structures  in  order  to  achieve  the  same  effect. 

Name  clashes  can  occur  when  using  program  definitions,  since  the  apparent  scoping  does  not  really  apply. 
Most  of  these  can  be  avoided  by  giving  unique  names  for  programs,  versions,  procedures  and  types. 
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NAME 

rsh  -  remote  shell 
SYNOPSIS 

rsh  [  username  ]  [  -n  ]  hostname  [  command  ] 
rsh  hostname  [  -I  username  ]  [  -n  ]  [  command  ] 

hostname  [  -I  username  ]  [  -n  ]  [  command  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4J 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

rsh  connects  to  the  specified  hostname  and  executes  the  specified  command,  rsh  copies  its  standard  input 
to  the  remote  command,  the  standard  output  of  the  remote  command  to  its  standard  ouQJut,  and  the  standard 
error  of  the  remote  command  to  its  standard  error.  Interrupt,  quit  and  terminate  signals  are  propagated  to 
the  remote  command;  rsh  normally  terminates  when  the  remote  command  does. 

If  you  omit  command^  instead  of  executing  a  single  command,  rsh  logs  you  in  on  the  remote  host  using 
rlogin(lC). 

Shell  metacharacters  which  are  not  quoted  are  interpreted  on  the  local  machine,  while  quoted  metacharac¬ 
ters  are  interpreted  on  the  remote  machine.  See  EXAMPLES. 

Hostnames  are  given  in  the  hosts  database,  which  may  be  contained  in  the  /etc/hosts  file,  the  Network  In¬ 
formation  Service  (NIS)  hosts  database,  the  Internet  domain  name  database,  or  some  combination  of  the 
three.  Each  host  has  one  official  name  (the  first  name  in  the  database  entry)  and  optionally  one  or  more 
nicknames.  Official  hostnames  or  nicknames  may  be  given  as  hostname. 

If  the  name  of  the  file  from  which  rsh  is  executed  is  anything  other  than  “rsh,”  rsh  takes  this  name  as  its 
hostname  argument.  This  allows  you  to  create  a  symbolic  link  to  rsh  in  the  name  of  a  host  which,  when 
executed,  will  invoke  a  remote  shell  on  that  host.  The  /usr/hosts  directory  is  provided  to  be  populated  with 
symbolic  links  in  the  names  of  commonly  used  hosts.  By  including  /usr/hosts  in  your  shell’s  search  path, 
you  can  run  rsh  by  typing  hostname  to  your  shell. 

Each  remote  machine  may  have  a  file  named  /etc/hosts.equiv  containing  a  list  of  trusted  hostnames  with 
which  it  shares  usernames.  Users  with  the  same  username  on  both  the  local  and  remote  machine  may  rsh 
from  the  machines  listed  in  the  remote  machine’s  /etc/hosts  file.  Individual  users  may  set  up  a  similar 
private  equivalence  list  with  the  file  .rhosts  in  their  home  directories.  Each  line  in  this  file  contains  two 
names:  a  hostname  and  a  username  separated  by  a  SPACE,  The  entry  permits  the  user  named  username 
who  is  logged  into  hostname  to  use  rsh  to  access  the  remote  machine  as  the  remote  user.  If  the  name  of  the 
local  host  is  not  found  in  the  /etc/hosts.equiv  file  on  the  remote  machine,  and  the  local  username  and  host- 
name  are  not  found  in  the  remote  user’s  .rhosts  file,  then  the  access  is  denied.  The  hostnames  listed  in  the 
/etc/hosts.equiv  and  .rhosts  files  must  be  the  official  hostnames  listed  in  the  hosts  database;  nicknames 
may  not  be  used  in  either  of  these  files. 

rsh  will  not  prompt  for  a  password  if  access  is  denied  on  the  remote  machine  unless  the  command  argu¬ 
ment  is  omited. 

OPTIONS 

-1  username 

Use  username  as  the  remote  username  instead  of  your  local  username.  In  the  absence  of  this  op¬ 
tion,  the  remote  username  is  the  same  as  your  local  username. 

~n  Redirect  the  input  of  rsh  to  /dev/null.  You  sometimes  need  this  opdon  to  avoid  unfortunate  in¬ 
teractions  between  rsh  and  the  shell  which  invokes  it.  For  example,  if  you  are  running  rsh  and 
start  a  rsh  in  the  background  without  redirecting  its  input  away  from  the  terminal,  it  will  block 
even  if  no  reads  are  posted  by  the  remote  command.  The  -n  option  will  prevent  this. 
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The  type  of  remote  shell  (sh,  rsh,  or  other)  is  determined  by  the  user’s  entry  in  the  file  /etc/passwd  on  the 
remote  system. 

EXAMPLES 

The  following  command  appends  the  remote  file  lizard.file  from  the  machine  called  lizard  to  the  file  called 
example.file  on  the  machine  called  example. 

example  %  rsh  lizard  cat  lizard.file  »  example.file 

This  example  appends  the  file  lizard.file  on  the  machine  called  lizard  to  the  file  another.lizard.file  which 
also  resides  on  the  machine  called  lizard. 

example  %  rsh  lizard  cat  lizard.file  "»"  another  .lizard.file 

FILES 

/etc/hosts 

/usr/hosts/* 

/etc/passwd 

SEE  ALSO 

rlogin(lC),  vi(l),  ypcat(l),  hosts(5),  named(8C),  rshd(8C) 

BUGS 

You  cannot  run  an  interactive  command  (such  as  vi(l));  use  rlogin  if  you  wish  to  do  so. 

Stop  signals  scop  the  local  rsh  process  only;  this  is  arguably  wrong,  but  currently  hard  to  fix  for  reasons  too 
complicated  to  explain  here. 

The  current  local  environment  is  not  passed  to  the  remote  shell. 

Sometimes  the  -n  option  is  needed  for  reasons  that  are  less  than  obvious.  For  example,  the  command 
below  puts  your  shell  into  a  strange  state. 

example%  rsh  somehost  dd  if=/d€v/nrmtO  bs=20b  |  tar  xvpBf- 

Evidently,  what  happens  is  that  the  tar  terminates  before  the  rsh.  The  rsh  then  tries  to  write  into  the  “bro¬ 
ken  pipe”  and,  instead  of  terminating  neatly,  proceeds  to  compete  with  your  shell  for  its  standard  input.  In¬ 
voking  rsh  with  the  -n  option  avoids  such  incidents. 

Note:  this  bug  occurs  only  when  rsh  is  at  the  beginning  of  a  pipeline  and  is  not  reading  standard  input.  Do 
not  use  the  -n  if  rsh  actually  needs  to  read  standard  input.  For  example,  the  following  command  does  not 
produce  the  bug. 

example%  tar  cf  - .  |  rsh  sundial  dd  of=/dev/rmtO  obs=20b 

If  you  were  to  use  the  -n  in  a  case  like  this,  rsh  would  incorrectly  read  from  /dev/null  instead  of  from  the 
pipe. 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed. 
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NAME 

nip  -  show  host  status  of  local  machines  (RPC  version) 

SYNOPSIS 

rup  [  -hit  ] 
rup  [  host...  j 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

rup  gives  a  status  similar  to  uptime  for  remote  machines.  It  broadcasts  on  the  local  network,  and  displays 
the  responses  it  receives. 

Normally,  the  listing  is  in  the  order  that  responses  are  received,  but  this  order  can  be  changed  by  specifying 
one  of  the  options  listed  below. 

When  host  arguments  are  given,  rather  than  broadcasting  rup  will  only  query  the  list  of  specified  hosts, 

A  remote  host  will  only  respond  if  it  is  running  the  rstatd  daemon,  which  is  normally  started  up  from 
inetd(8C). 

OPTIONS 

-h  Sort  the  display  alphabetically  by  host  name. 

-I  Sort  the  display  by  load  average. 

-t  Sort  the  display  by  up  time. 

FILES 

/etc/servers 
SEE  ALSO 

ruptime(lC),  inetd(8C),  rstatd(8C) 

BUGS 

Broadcasting  does  not  work  through  gateways. 
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NAME 

ruptime  -  show  host  status  of  local  machines 

SYNOPSIS 

ruptime  [  -alrtu  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

ruptime  gives  a  status  line  like  uptime  for  each  machine  on  the  local  network;  these  are  formed  from 
packets  broadcast  by  each  host  on  the  network  once  a  minute. 

Machines  for  which  no  status  report  has  been  received  for  5  minutes  are  shown  as  being  down. 

Normally,  the  listing  is  sorted  by  host  name,  but  this  order  can  be  changed  by  specifying  one  of  the  options 
listed  below. 

OPTIONS 

-a  Count  even  those  users  who  have  been  idle  for  an  hour  or  more. 

”1  Sort  the  display  by  load  average. 

~r  Reverse  the  sorting  order. 

-t  Sort  the  display  by  up  time. 

-u  Sort  the  display  by  number  of  users. 

FILES 

/var/spool/rwho/whod.* 
data  hies 

SEE  ALSO 

rup(lC),  rwho(lC) 
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NAME 

nisers  -  who’s  logged  in  on  local  machines  (RPC  version) 

SYNOPSIS 

rusers  [  -ahilu  ]  [  host. . .  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4J 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

The  rusers  command  produces  output  similar  to  users(l)  and  who(l),  but  for  remote  machines.  It  broad¬ 
casts  on  the  local  network,  and  prints  the  responses  it  receives.  Normally,  the  listing  is  in  the  order  that 
responses  are  received,  but  this  order  can  be  changed  by  specifying  one  of  the  options  listed  below.  When 
host  arguments  are  given,  rather  than  broadcasting  rusers  will  only  query  the  list  of  specified  hosts. 

The  default  is  to  print  out  a  listing  in  the  style  of  users(l)  with  one  line  per  machine.  When  the  -I  flag  is 
given,  a  rwho(lC)  style  listing  is  used.  In  addition,  if  a  user  has  not  typed  to  the  system  for  a  minute  or 
more,  the  idle  time  is  reported. 

A  remote  host  will  only  respond  if  it  is  running  the  rusersd  daemon,  which  is  normally  started  up  from 
inetd(8C). 

OPTIONS 

-a  Give  a  report  for  a  machine  even  if  no  users  are  logged  on. 

-h  Sort  alphabetically  by  host  name. 

“i  Sort  by  idle  time. 

-I  Give  a  longer  listing  in  the  style  of  who(l). 

-u  Sort  by  number  of  users. 

FILES 

/etc/inetdxonf 
SEE  ALSO 

rwho(lC),  users(l),  who(l),  inetd(8C),  rusersd(8C) 

BUGS 

Broadcasting  does  not  work  through  gateways. 
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NAME 

rwall  -  write  to  all  users  over  a  network 
SYNOPSIS 

/usr/etc/rwall  hostname., . 

/usr/etc/rwall  -n  netgroup, . . 

/usr/etc/rwall  -h  hostname  -n  netgroup 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

rwall  reads  a  message  from  standard  input  until  EOF.  It  then  sends  this  message,  preceded  by  the  line 
'Broadcast  Message  to  all  users  logged  in  on  the  specified  host  machines.  With  the  -n  option,  it 
sends  to  the  specified  network  groups,  which  are  defined  in  netgroup(5). 

A  machine  can  only  receive  such  a  message  if  it  is  running  rwalld(8C),  which  is  normally  started  up  from 
/etc/inetd.conf  by  the  daemon  inetd(8C). 

FILES 

/etc/inetd.conf 
SEE  ALSO 

wall(l),  netgroup(5),  inetd(8C),  rwalId(8C),  shutdown(8) 

BUGS 

The  timeout  is  fairly  short  in  order  to  be  able  to  send  to  a  large  group  of  machines  (some  of  which  may  be 
down)  in  a  reasonable  amount  of  time.  Thus  the  message  may  not  get  through  to  a  heavily  loaded  machine. 
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NAME 

rwho  -  who’s  logged  in  on  local  machines 

SYNOPSIS 

rwho  [  -a  ] 

AVAILABILITY 

The  rwho  service  daemon,  rwhdd(8C)  must  be  enabled  for  this  command  to  return  useful  results.  Refer  to 
finger(l),  rup(lC)  and  rusers(lC)  for  alternatives. 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  infonnation  on  how  to  install  optional  software. 

DESCRIPTION 

The  rwho  command  produces  output  similar  to  who(l),  but  for  all  machines  on  your  network.  If  no  report 
has  been  received  from  a  machine  for  5  minutes,  rwho  assumes  the  machine  is  down,  and  does  not  report 
users  last  known  to  be  logged  into  that  machine. 

If  a  user  has  not  typed  to  the  system  for  a  minute  or  more,  rwho  reports  this  idle  time.  If  a  user  has  not 
typed  to  the  system  for  an  hour  or  more,  the  user  is  omitted  from  the  output  of  rwho  unless  the  -a  flag  is 
given. 

OPTIONS 

-a  Report  all  users  whether  or  not  they  have  typed  to  the  system  in  the  past  hour. 

FILES 

/  var/spool/rwho/whod.* 

information  about  other  machines 

SEE  ALSO 

finger(l),  rup(lC),  ruptime(lC),  rusers(lC),  who(l),  rwhod(8C) 

BUGS 

Does  not  work  through  gateways. 

This  is  unwieldy  when  the  number  of  machines  on  the  local  net  is  large. 
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NAME 

sees  -  front  end  for  the  Souree  Code  Control  System  (SCCS) 

SYNOPSIS 

SCCS  [  -r  ]  [  -drootprefix  ]  [  -psubdir  ]  subcommand  [  option  . . .  ]  [filename  . . .  ] 

DESCRIPTION 

The  sees  command  is  a  comprehensive,  straightforward  front  end  to  the  various  utility  programs  of  the 
Source  Code  Control  System  (SCCS). 

sees  applies  the  indicated  subcommand  to  the  history  file  associated  with  each  of  the  indicated  files. 

The  name  of  an  SCCS  history  file  is  derived  by  prepending  the  ‘s/  prefix  to  the  filename  of  a  working 
copy.  The  secs  command  normally  expects  these  ‘s.files’  to  reside  in  an  SCCS  subdirectory.  Thus,  when 
you  supply  secs  with  a  filename  argument,  it  normally  applies  the  subcommand  to  a  file  named  s  filename 
in  the  SCCS  subdirectory.  If  filename  is  a  pathname,  secs  looks  for  the  history  file  in  the  SCCS  subdirecto¬ 
ry  of  that  file’s  parent  directory.  If  filename  is  a  directory,  however,  sees  applies  the  subcommand  to  every 
s.file  file  it  contains.  Thus,  the  command: 

sees  get  prograntx 

would  apply  the  get  subcommand  to  a  history  file  named: 

S  CCS/s.program  .e 
while  the  command: 

secs  get  SCCS 

would  apply  it  to  every  s,file  in  the  SCCS  subdirectory. 

Options  for  the  sees  command  itself  must  appear  before  the  subcommand  argument.  Options  for  a  given 
subcommand  must  appear  after  the  subcommand  argument.  These  options  are  specific  to  each  subcom¬ 
mand,  and  are  described  along  with  the  subcommands  themselves  (see  Subcommands,  below). 

Running  Setuid 

The  sees  command  also  includes  the  capability  to  run  “setuid”  to  provide  additional  protection.  However 
this  does  not  apply  to  subcommands  such  as  sccs-admin(l),  since  this  would  allow  anyone  to  change  the 
authorizations  of  the  history  file.  Commands  that  would  do  so  always  run  as  the  real  user. 

OPTIONS 

-r  Run  sees  with  the  real  user  ID,  rather  than  set  to  the  effective  user  ID. 

-drootprefix 

Define  the  root  portion  of  the  pathname  for  SCCS  history  files.  The  default  root  portion  is  the 
current  directory.  Note:  rootprefix  is  prepended  to  the  entire  filename  argument,  even  if  filename 
is  an  absolute  pathname,  -d  overrides  any  directory  specified  by  the  PROJECTDIR  environment 
variable  (see  ENVIRONMENT,  below), 

-psubdir 

Define  the  (sub)directory  within  which  a  history  file  is  expected  to  reside.  SCCS  is  the  default. 
(See  EXAMPLES,  below). 

USAGE 

Subcommands 

Many  of  the  following  secs  subcommands  invoke  programs  that  reside  in  /usr/secs.  Many  of  these  sub¬ 
commands  accept  additional  arguments  that  are  documented  in  the  reference  page  for  the  utility  program 
the  subcommand  invokes. 

admin  Modify  the  flags  or  checksum  of  an  SCCS  history  file.  Refer  to  sccs-admin(l)  for  more  informa¬ 
tion  about  the  admin  utility.  While  admin  can  be  used  to  initialize  a  history  file,  you  may  find 
that  the  create  subcommand  is  simpler  to  use  for  this  purpose. 
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cdc  -rsid  [  -~y[comment]  ] 

Annotate  (change)  the  delta  commentary.  Refer  to  sccs-cdc(l).  Note:  the  fix  subcommand  can  be 
used  to  replace  the  delta,  rather  than  merely  annotating  the  existing  commentary. 

-rsid  Specify  the  SCCS  delta  ID  (SID)  to  which  the  change  notation  is  to  be  added. 
The  SID  for  a  given  delta  is  a  number,  in  Dewey  decimal  format,  composed  of 
two  or  four  fields:  the  release  and  level  fields,  and  for  branch  deltas,  the  branch 
and  sequence  fields.  For  instance,  the  SID  for  the  initial  delta  is  normally  1.1. 

-ylcomment] 

Specify  the  comment  with  which  to  annotate  the  delta  commentary.  If  -y  is  om¬ 
itted,  sees  prompts  for  a  comment.  A  null  comment  results  in  an  empty  annota¬ 
tion. 

check  [-b]  [-\i[username\] 

Check  for  files  currendy  being  edited.  Like  info  and  tell,  but  returns  an  exit  code,  rather  than  pro¬ 
ducing  a  listing  of  files,  check  returns  a  non-zero  exit  status  if  anything  is  being  edited. 

-b  Ignore  branches. 

-ulusername^ 

Only  check  files  being  edited  by  you.  When  username  is  specified,  only  check 
files  being  edited  by  that  user. 

clean  [-b] 

Remove  everything  in  the  current  directory  that  can  be  retrieved  firom  an  SCCS  history.  Does  not 
remove  files  that  are  being  edited. 

-b  Do  not  check  branches  to  see  if  they  are  being  edited,  ‘clean  -b’  is  dangerous 
when  branch  versions  are  kept  in  the  same  directory. 

comb  Generate  scripts  to  combine  deltas.  Refer  to  sccs-comb(l). 

create  Create  (initialize)  history  files,  create  performs  the  following  steps: 

•  Renames  the  original  source  file  to  ,program.c  in  the  current  directory. 

•  Create  the  history  file  called  s.program.c  in  the  SCCS  subdirectory. 

•  Performs  an  ‘sees  get’  on  program.c  to  retrieve  a  read-only  copy  of  the  initial  version. 

deledit  [-s]  [-y[comment]  ] 

Equivalent  to  an  ‘sees  delta’  and  then  an  ‘sees  edit’,  deledit  checks  in  a  delta,  and  checks  the  file 
back  out  again,  but  leaves  the  current  working  copy  of  the  file  intact. 

-s  Silent.  Do  not  report  delta  numbers  or  statistics. 

-y[comment] 

Supply  a  comment  for  the  delta  commentary.  If  -y  is  omitted,  delta  prompts  for 
a  comment.  A  NULL  comment  results  in  an  empty  comment  field  for  the  delta. 

delget  [-s]  [-yicomment]  ] 

Perform  an  ‘sees  delta’  and  then  an  ‘sees  get’  to  check  in  a  delta  and  retrieve  read-only  copies  of 
the  resulting  new  version.  See  the  deledit  subcommand  for  a  description  of  -s  and  -y.  sees  per¬ 
forms  a  delta  on  all  the  files  specified  in  the  argument  list,  and  then  a  get  on  all  the  files.  If  an  er¬ 
ror  occurs  during  the  delta,  the  get  is  not  performed. 

delta  [-s]  [-yicomment]  ] 

Check  in  pending  changes.  Records  the  line-by-line  changes  introduced  while  the  file  was 
checked  out.  The  effective  user  ID  must  be  the  same  as  the  ID  of  the  person  who  has  the  file 
checked  out.  Refer  to  sccs-delta(l).  See  the  deledit  subcommand  for  a  description  of  -s  and  ~y. 
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diffs  [-C]  [-cdate-time]  [-rsid]  diff-options 

Compare  (in  diff(l)  format)  the  working  copy  of  a  file  that  is  checked  out  for  editing,  with  a  ver¬ 
sion  from  the  SCCS  history.  Use  the  most  recent  checked-in  version  by  default.  The  diffs  sub¬ 
command  accepts  the  same  options  as  diff,  with  the  exception  that  the  -c  option  to  diff  must  be 
specified  as  ~C. 

-C  Pass  the  -c  option  to  diff. 

-cdate-time 

Use  the  most  recent  version  checked  in  before  the  indicated  dale  and  time  for 
comparison,  date-time  takes  the  form:  yy[mm[dd[hh[mm[ss]  ]  ]  ]  ].  Omitted  un¬ 
its  default  to  their  maximum  possible  values;  that  is  -c7502  is  equivalent  to 
-C750228235959, 

-rsid  Use  the  version  corresponding  to  the  indicated  delta  for  comparison. 

edit  Retrieve  a  version  of  the  file  for  editing,  ‘sees  edit’  extracts  a  version  of  the  file  that  is  writable 
by  you,  and  creates  a  p.file  in  the  SCCS  subdirectory  as  lock  on  the  history,  so  that  no  one  else  can 
check  that  version  in  or  out.  ID  keywords  are  retrieved  in  unexpanded  form,  edit  accepts  the 
same  options  as  get,  below. 

enter  Similar  to  create,  but  omits  the  final  ‘sees  get’.  TTiis  may  be  used  if  an  ‘secs  edit’  is  to  be  per¬ 
formed  immediately  after  the  history  file  is  initialized. 

fix  -rsid 

Revise  a  (leaf)  delta.  Remove  the  indicated  delta  from  the  SCCS  history,  but  leave  a  working  copy 
of  the  current  version  in  the  directory.  This  is  useful  for  incorporating  trivial  updates  for  which  no 
audit  record  is  needed,  or  for  revising  the  delta  commentary,  fix  must  be  followed  by  a  -r  option, 
to  specify  the  SID  of  the  delta  to  remove.  The  indicated  delta  must  be  the  most  recent  (leaf)  delta 
in  its  branch.  Use  fix  with  caution  since  it  does  not  leave  an  audit  trail  of  differences  (although  the 
previous  commentary  is  retained  within  the  history  file). 

get  [-ekmps]  [-edate-time]  [-rsid] 

Retrieve  a  version  fi'om  the  SCCS  history.  By  default,  this  is  a  read-only  working  copy  of  the  most 
recent  version;  ID  keywords  are  in  expanded  form.  Refer  to  sccs-get(l). 

-e  Retrieve  a  version  for  editing.  Same  as  secs  edit. 

-k  Retrieve  a  writable  copy  but  do  not  check  out  the  file.  ID  keywords  are  unex¬ 
panded, 

-m  Precede  each  line  with  the  SID  of  the  delta  in  which  it  was  added. 

-p  Produce  the  retrieved  version  on  the  standard  output.  Reports  that  would  nor¬ 
mally  go  to  the  standard  output  (delta  ID’s  and  statistics)  are  directed  to  the  stan¬ 
dard  error. 

-s  Silent.  Do  not  report  version  numbers  or  statistics. 

-edate-time 

Retrieve  the  latest  version  checked  in  prior  to  the  date  and  time  indicated  by  the 
date-time  argument,  date-time  takes  the  form:  yy  [mm  [dd[hh  [mm [jj]  ]  ]  ]  ]. 

-rsid  Retrieve  the  version  corresponding  to  the  indicated  SID. 

help  message-code\sccs-command 

help  stuck 

Supply  more  information  about  SCCS  diagnostics,  help  displays  a  brief  explanation  of  the  error 
when  you  supply  the  code  displayed  by  an  SCCS  diagnostic  message.  If  you  supply  the  name  of 
an  SCCS  command,  it  prints  a  usage  line,  help  also  recognizes  the  keyword  stuck.  Refer  to  sccs- 
help(l). 
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info  [-b]  [-u[username]  ] 

Display  a  list  of  files  being  edited,  including  the  version  number  checked  out,  the  version  to  be 
checked  in,  the  name  of  the  user  who  holds  the  lock,  and  the  date  and  time  the  file  was  checked 
out. 


-b  Ignore  branches. 

-u[username] 

Only  list  files  checked  out  by  you.  When  username  is  specified,  only  list  files 
checked  out  by  that  user. 

print  Print  the  entire  history  of  each  named  file.  Equivalent  to  an  ‘sees  prs  -e’  followed  by  an  ‘secs 
get-p-m’. 

prs  [-el]  [-edate-time] 

Peruse  (display)  the  delta  table,  or  other  portion  of  an  s.file.  Refer  to  sccs-prs(l). 

-e  Display  delta  table  information  for  all  deltas  earlier  than  the  one  specified  with 
-r  (or  all  deltas  if  none  is  specified), 

-I  Display  information  for  all  deltas  later  than,  and  including,  that  specified  by  -c 
or  -r. 

-edate-time 

Specify  the  latest  delta  checked  in  before  the  indicated  date  and  time.  The 
date-time  argument  takes  the  form:  yy[mm  [dd[hh  [mm  [s5]  ]  ]  ]  ] . 

-rsid  Specify  a  given  delta  by  SID. 

prt  [~y]  Display  the  delta  table,  but  omit  the  MR  field  (see  sccsfile(5)  for  more  information  on  this  field). 
Refer  to  sccs-prt(l). 

-y  Display  the  most  recent  delta  table  entry.  The  format  is  a  single  output  line  for 
each  filename  argument,  which  is  convenient  for  use  in  a  pipeline  with  awk(l) 
or  sed(lV). 

rmdel  -rsid 

Remove  the  indicated  delta  from  the  history  file.  That  delta  must  be  the  most  recent  (leaf)  delta  in 
its  branch.  Refer  to  sccs-rmdel(l). 

scesdifT  -rold-sid  -rnew-sid  dijf-options 

Compare  two  versions  corresponding  to  the  indicated  SIDs  (deltas)  using  diff.  Refer  to  sccs- 
sccsdiff(l). 

teW  [~b]  [-u[username]] 

Display  the  list  of  files  that  are  currently  checked  out,  one  filename  per  line. 

-b  Ignore  branches. 

~u[username] 

Only  list  files  checked  out  to  you.  When  username  is  specified,  only  list  files 
check  out  to  that  user. 

unedit  “Undo”  the  last  edit  or  ‘get  -e’,  and  return  the  working  copy  to  its  previous  condition,  unedit 
backs  out  all  pending  changes  made  since  the  file  was  checked  out. 

unget  Same  as  unedit  Refer  to  sccs-unget(l). 

val  Validate  the  history  file.  Refer  to  sccs-val(l). 

what  Display  any  expanded  ID  keyword  strings  contained  in  a  binary  (object)  or  text  file.  Refer  to 
what(l)  for  more  information. 
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ENVIRONMENT 

If  the  environment  variable  PROJECT0IR  is  set  to  contain  an  absolute  pathname  (beginning  with  a  slash), 
sees  searches  for  SCCS  history  files  in  the  directory  given  by  that  variable.  If  PROJECTDIR  does  not  begin 
with  a  slash,  it  is  taken  as  the  name  of  a  user,  and  secs  searches  the  sre  or  source  subdirectory  of  that 
user’s  home  directory  for  history  files, 

EXAMPLES 

SCCS  converts  the  command: 

sees  -d/usr/src/include  get  stdio.h 
to: 

/usr/sccs/ get  /usr/src/include/SCCS/s.stdio,h 
The  command: 

sees  -pprivate  get  include/stdio.h 
becomes: 

/usr/sccs/get  include/private/s.stdio.h 

To  initialize  the  history  file  for  a  source  file  named  program.c:  make  the  SCCS  subdirectory,  and  then  use 
‘secs  create’: 

example  %  mkdir  SCCS 
example  %  secs  create  program.c 
program.c: 

1.1 

14  lines 

After  verifying  the  working  copy,  you  can  remove  the  backup  file  that  starts  with  a  comma: 

example%  dilf  program.c  , program.c 
example  %  rm  ,program.c 

To  check  out  a  copy  of  program.c  for  editing,  edit  it,  and  then  check  it  back  in: 

example  %  sees  edit  program.c 

1.1 

new  delta  1.2 

14  lines 

example  %  vi  program. c 
your  editing  session 
example  %  sees  delget  program.c 
comments?  clarified  cryptic  diagnostic 
1.2 

3  inserted 
2  deleted 
12  unchanged 
1.2 

15  lines 

To  retrieve  a  file  from  another  directory  into  the  current  directory: 

example%  sees  get  /usr/src/sccs/cc.c 
or: 

example  %  sees  -p/usr/src/sccs/  get  cc.c 
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To  check  out  all  files  under  SCCS  in  the  current  directory: 

example  %  sees  edit  SCCS 
To  check  in  all  files  currently  checked  out  to  you: 
example  %  secs  delta  'secs  tell  -u' 

FILES 


SCCS 

SCCS  subdirectory 

SCCS/d,^/e 

temporary  file  of  differences 

SCCSlpfile 

lock  (permissions)  file  for  checked-out  versions 

SCCSfq.file 

temporary  file 

SCCS/sjile 

SCCS  history  file 

SCCS/xJile 

temporary  copy  of  the  s.file 

SCCSfz.file 

temporary  lock  file 

/usr/sees/* 

SCCS  utility  programs 

SEE  ALSO 

awk(l),  diff(l),  sccs-admiii(l),  sccs-cdc(l),  sccs-comb(l),  sccs-delta(l),  sccs-get(l),  sccs-help(l),  sccs- 
prs(l),  sccs-rmdel(l),  sccs-sact(l),  sccs-sccsdiff(l),  sccs-unget(l),  sccs-val(l),  sed(lV),  what(l), 
sccsfile(5) 

Programming  Utilities  and  Libraries 

BUGS 

There  is  no  saet  subcommand  to  invoke  /usr/sees/sact  (see  sccS“Sact(l)).  However,  the  info  subcommand 
performs  an  equivalent  function. 
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NAME 

sccs-admin,  admin  -  create  and  administer  SCCS  history  files 
SYNOPSIS 

/usr/sccs/admin  [ -bhnz ]  [ -ausernamelgroupid ] . . .  [ -dflag  ] . . .  [ -eusernamelgroupid ]  ... 

[  -tflag  [  value  ] } . . .  [  -i  [filename  ]  ]  [  ~1  alrelease  [^release, . .  ]  ]  [  -m  mr-list  ]  [  -~r release  ] 

[  -t  [  description-file  ]  ]  [  ~y  [comment]  ]  s. filename  . . . 

DESCRIPTION 

admin  creates  or  modifies  the  flags  and  other  parameters  of  SCCS  history  files.  Filenames  of  SCCS  history 
files  begin  with  the  *s.’  prefix,  and  are  referred  to  as  s.files,  or  “history”  files. 

The  named  s«file  is  created  if  it  does  not  exist  already.  Its  parameters  are  initialized  or  modified  according 
to  the  options  you  specify.  Parameters  not  specified  are  given  default  values  when  the  file  is  initialized, 
otherwise  they  remain  unchanged. 

If  a  directory  name  is  used  in  place  of  the  s.filename  argument,  the  admin  command  applies  to  all  s.files  in 
that  directory.  Unreadable  s.files  produce  an  error.  The  use  of  as  the  s.filename  argument  indicates  that 
the  names  of  files  are  to  be  read  from  the  standard  input,  one  s.file  per  line. 

OPTIONS 

“b  Force  encoding  of  binary  data.  Files  that  contain  ASCII  NUL  or  other  control  characters,  or  that  do 
not  end  with  a  NEWUNE,  are  recognized  as  binary  data  files.  The  contents  of  such  files  are  stored 
in  the  history  file  in  encoded  form.  See  uuencode(lC)  for  details  about  the  encoding.  This  option 
is  normally  used  in  conjunction  with  -i  to  force  admin  to  encode  initial  versions  not  recognized 
as  containing  binary  data. 

-h  Check  the  structure  of  an  existing  s.file  (see  sccsfile(5)),  and  compare  a  newly  computed  check¬ 
sum  with  one  stored  in  the  first  line  of  that  file,  -h  inhibits  writing  on  the  file;  and  so  nullifies  the 
effect  of  any  other  options. 

-n  Create  a  new  SCCS  history  file. 

-z  Recompute  the  file  check-sum  and  store  it  in  the  first  line  of  the  s.file.  Caution:  it  is  important  to 
verify  the  contents  of  the  history  file  (see  sccs-val(l),  and  the  print  subcommand  in  sccs(l)), 
since  using  -z  on  a  truly  corrupted  file  may  prevent  detection  of  the  error. 

-2iUsername\groupid 

Add  a  user  name,  or  a  numerical  group  ID,  to  the  list  of  users  who  may  check  deltas  in  or  out.  If 
the  list  is  empty,  any  user  is  allowed  to  do  so. 

-dflag  Delete  the  indicated  flag  from  the  SCCS  file.  The  -d  option  may  be  specified  only  for  existing 
s.files.  See  -f  for  the  list  of  recognized  flags. 

-eusername\groupid 

Erase  a  user  name  or  group  ID  from  the  list  of  users  allowed  to  make  deltas. 

-fflag  [value] 

Set  the  indicated  flag  to  the  (optional)  value  specified.  The  following  flags  are  recognized: 

b  Enable  branch  deltas.  When  b  is  set,  branches  can  be  created  using  the  -b  op¬ 
tion  of  the  SCCS  get  command  (see  sccs-get(l)). 

cceil  Set  a  ceiling  on  the  releases  that  can  be  checked  out.  ceil  is  a  number  less  than 
or  equal  to  9999.  If  c  is  not  set,  the  ceiling  is  9999. 

ffloor  Set  a  floor  on  the  releases  that  can  be  checked  out.  The  floor  is  a  number  greater 
than  0  but  less  than  9999.  If  f  is  not  set,  the  floor  is  1. 

dsid  The  default  delta  number,  or  SID,  to  be  used  by  an  SCCS  get  command. 
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i  Treat  the  ‘No  id  keywords  (ge6)’  message  issued  by  an  SCCS  get  or  delta  com¬ 
mand  as  an  error  rather  than  a  warning. 

j  Allow  concurrent  updates. 

la 

Ireleasel^release  . . .  ] 

Lock  the  indicated  list  of  releases  against  deltas.  If  a  is  used,  lock  out  deltas  to 
all  releases.  An  SCCS  ‘get  -e’  command  fails  when  applied  against  a  locked 
release. 

n  Create  empty  releases  when  releases  are  skipped.  These  null  (empty)  deltas 
serve  as  anchor  points  for  branch  deltas. 

qvalue  Supply  a  value  to  which  the  %Q%  keyword  is  to  expand  when  a  read-only  ver¬ 
sion  is  retrieved  with  the  SCCS  get  command. 

mmodtde 

Supply  a  value  for  the  module  name  to  which  the  %M%  keyword  is  to  expand. 
If  the  m  flag  is  not  specified,  the  value  assigned  is  the  name  of  the  SCCS  file 
with  the  leading  s.  removed. 

ttype  Supply  a  value  for  the  module  type  to  which  the  % Y%  keyword  is  to  expand. 

V  [program] 

Specify  a  validation  program  for  the  MR  numbers  associated  with  a  new  delta. 
The  optional  program  specifies  the  name  of  an  MR  number  validity  checking 
program.  If  this  flag  is  set  when  creating  an  SCCS  file,  the  — m  option  must  also 
be  used,  in  which  case  the  list  of  MRs  may  be  empty. 

-i  [filename] 

Initialize  the  history  file  with  text  from  the  indicated  file.  This  text  constitutes  the  initial  delta,  or 
set  of  checked-in  changes.  If  filename  is  omitted,  the  initial  text  is  obtained  from  the  standard  in¬ 
put.  Omitting  the  -i  option  altogether  creates  an  empty  s.file.  You  can  only  initialize  one  s.file 
with  text  using  -i.  This  option  implies  the  -n  option. 

-la 

-\release  [, release. . .  ] 

Unlock  the  specified  releases  so  that  deltas  can  be  checked  in.  If  a  is  specified,  allow  deltas  to  be 
checked  in  for  all  releases. 

-m  [mr-fisr] 

Insert  the  indicated  Modification  Request  (MR)  numbers  into  the  commentary  for  the  initial  ver¬ 
sion.  When  specifying  more  than  one  MR  number  on  the  command  line,  mr-list  takes  the  form  of 
a  quoted,  space-separated  list.  A  warning  results  if  the  v  flag  is  not  set  or  the  MR  validation  fails. 

-rrelease 

Specify  the  release  for  the  initial  delta,  -r  may  be  used  only  in  conjunction  with  -i.  The  initial 
delta  is  inserted  into  release  1  if  this  option  is  omitted.  The  level  of  the  initial  delta  is  always  1; 
initial  deltas  are  named  1.1  by  default. 

-t  [description-file] 

Insert  descriptive  text  from  the  file  description-file.  When  -t  is  used  in  conjunction  with  ~n,  or  -i 
to  initialize  a  new  s.file,  the  description-file  must  be  supplied.  When  modifying  the  description  for 
an  existing  file:  a  -t  option  without  a  description-file  removes  the  descriptive  text,  if  any;  a  -t  op¬ 
tion  with  a  description-file  replaces  the  existing  text. 

-y  [  comment  ] 

Insert  the  indicated  comment  in  the  “Comments:’'  field  for  the  initial  delta.  Valid  only  in  con¬ 
junction  with  -i  or  -n.  If  -y  option  is  omitted,  a  default  comment  line  is  inserted  that  notes  the 
date  and  time  the  history  file  was  created. 
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FILES 

s.*  history  file 

SCCS/s.+  history  file  in  SCCS  subdirectory 

z.*  temporary  lock  file 

WARNINGS 

The  last  component  of  all  SCCS  filenames  must  have  the  ‘s.’  prefix.  New  SCCS  files  are  given  mode  444 
(see  chmod(lV)).  All  writing  done  by  admin  is  to  a  temporary  file  with  an  x.  prefix,  created  with  mode 
444  for  a  new  SCCS  file,  or  with  the  same  mode  as  an  existing  SCCS  file.  After  successful  execution  of  ad¬ 
min,  the  existing  s.  file  is  removed  and  replaced  with  the  x.file.  This  ensures  that  changes  are  made  to  the 
SCCS  file  only  when  no  errors  have  occurred. 

It  is  recommended  that  directories  containing  SCCS  files  have  permission  mode  755,  and  that  the  s.files 
themselves  have  mode  444.  The  mode  for  directories  allows  only  the  owner  to  modify  the  SCCS  files  con¬ 
tained  in  the  directories,  while  the  mode  of  the  s.files  prevents  all  modifications  except  those  performed  us¬ 
ing  SCCS  commands. 

If  it  should  be  necessary  to  patch  an  SCCS  file  for  any  reason,  the  mode  may  be  changed  to  644  by  the  own¬ 
er  to  allow  use  of  a  text  editor.  However,  extreme  care  must  be  taken  when  doing  this.  The  edited  file 
should  always  be  processed  by  an  ‘admin  —h’  to  check  for  corruption,  followed  by  an  ‘admin  — z’  to  gen¬ 
erate  a  proper  check-sum.  Another  ‘admin  -h’  is  recommended  to  ensure  that  the  resulting  s.file  is  valid. 

admin  also  uses  a  temporary  lock  s.file,  starting  with  the  ‘z/  prefix,  to  prevent  simultaneous  updates  to  the 
s.file.  See  sccs-get(l)  for  further  information  about  the  ‘z.file’. 

SEE  ALSO 

sccs(l),  sccs-cdc(l),  sccs-d€lta(l),  sccs-get(l),  sccs-help(l),  sccs-rmdel(l),  sccs-val(l),  sccsfile(5) 
Programming  Utilities  and  Libraries. 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (see  sccs-help(l)). 
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NAME 

sccs-cdc,  cdc  -  change  the  delta  commentary  of  an  SCCS  delta 

SYNOPSIS 

/usr/sccs/cdc  -rsid  [  -mmr-list  ]  [  -y  [  comment  ]  ]  s.filename  . . . 

DESCRIPTION 

cdc  annotates  the  delta  commentary  for  the  SCCS  delta  ID  (SID)  specified  by  the  -r  option  in  each  named 
s.file. 

If  the  V  flag  is  set  in  the  s.file,  you  can  also  use  cdc  to  update  the  Modification  Request  (MR)  list. 

If  you  checked  in  the  delta,  or,  if  you  own  the  file  and  directory  and  have  write  permission,  you  can  use  cdc 
to  annotate  the  commentary. 

Rather  than  replacing  the  existing  commentary,  cdc  inserts  the  new  comment  you  supply,  followed  by  a 
line  of  the  form: 

*+*  CHANGED  *+*  yylmmidd  hhimmiss  username 
above  the  existing  commentary. 

If  a  directory  is  named  as  the  s.filename  argument,  the  cdc  command  applies  to  all  s.files  in  that  directory. 
Unreadable  s.files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  If  is  given  as  the 
s.filename  argument,  each  line  of  the  standard  input  is  taken  as  the  name  of  an  SCCS  history  file  to  be  pro¬ 
cessed,  and  the  -m  and  -y  options  must  be  used. 

OPTIONS 

-Tsid  Specify  the  SID  of  the  delta  to  change. 

-mmr-list  Specify  one  or  more  MR  numbers  to  add  or  delete.  When  specifying  more  than  one  MR 
on  the  command  line,  mr-list  takes  the  form  of  a  quoted,  space-separated  list.  To  delete 
an  MR  number,  precede  it  with  a  !  character  (an  empty  MR  list  has  no  effect).  A  list  of 
deleted  MRs  is  placed  in  the  comment  section  of  the  delta  commentary.  If-m  is  not  used 
and  the  standard  input  is  a  terminal,  cdc  prompts  with  MRs?  for  the  list  (before  issuing 
the  comments?  prompt),  -m  is  only  useful  when  the  v  flag  is  set  in  the  s.file.  If  that  flag 
has  a  value,  it  is  taken  to  be  the  name  of  a  program  to  validate  the  MR  numbers.  If  that 
validation  program  returns  a  non-zero  exit  status,  cdc  terminates  and  the  delta  commen¬ 
tary  remains  unchanged. 

-ylcomment] 

Use  comment  as  the  annotation  in  the  delta  commentary.  The  previous  comments  are 
retained;  the  comment  is  added  along  with  a  notation  that  the  commentary  was  changed. 
A  null  comment  leaves  the  commentary  unaffected.  If  -y  is  not  specified  and  the  stan¬ 
dard  input  is  a  terminal,  cdc  prompts  with  comments?  for  the  text  of  the  notation  to  be 
added.  An  unescaped  NEWLINE  character  terminates  the  annotation  text, 

EXAMPLES 

The  following  command: 

example%  cdc -r  1.6 -y" corrected  commentary”  s.program.c 
produces  the  following  annotated  commentary  for  delta  1.6  in  s.program.c: 


D  1.6  88/07/05  23:21:07  username  9  0  00001/00000/00000 
MRs: 

COMMENTS: 
corrected  commentary 

***  CHANGED  ++*  88/07/07  14:09:41  username 
performance  enhancements  in  main() 
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FILES 

temporary  lock  file 

SEE  ALSO 

sccs(l),  sccs-admm(l),  sccs-comb(l),  sccs-deUa(l),  sccs-help(l),  sccs-prs(l).  sccs-prt(l),  sccs-rmdel(l), 
what(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (sccs-help(l)). 
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NAME 

sccs-comb,  comb  -  combine  SCCS  deltas 
SYNOPSIS 

/usr/sccs/comb  [  ~os  ]  [  -csid-Ust  ]  [  -psid  ]  s.filename  . . . 

DESCRIPTION 

comb  generates  a  shell  script  (see  sh(l))  that  you  can  use  to  reconstruct  the  indicated  s.files.  This  script  is 
written  to  the  standard  output. 

If  a  directory  name  is  used  in  place  of  the  s.jilencane  argument,  the  comb  command  applies  to  all  s.files  in 
that  directory.  Unreadable  s.files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The 
use  of  as  the  s.filename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard  in¬ 
put,  one  s.file  per  line. 

If  no  options  are  specified,  comb  preserves  only  the  most  recent  (leaf)  delta  in  a  branch,  and  the  minimal 
number  of  ancestors  needed  to  preserve  the  history. 

OPTIONS 

-o  For  each  ‘get  -e"  generated,  access  the  reconstructed  file  at  the  release  of  the  delta  to  be  created. 
Otherwise,  the  reconstructed  file  is  accessed  at  the  most  recent  ancestor.  The  use  of  -o  may  de¬ 
crease  the  size  of  the  reconstructed  s.file.  It  may  also  alter  the  shape  of  the  delta  tree  of  the  origi¬ 
nal  file. 

-s  Generate  scripts  to  gather  statistics,  rather  than  combining  deltas.  When  run,  the  shell  scripts  re¬ 
port:  the  file  name,  size  (in  blocks)  after  combining,  original  size  (also  in  blocks),  and  the  percen¬ 
tage  size  change,  computed  by  the  formula: 

100  +  (  original  -  combined  )  /  original 

This  option  can  be  used  to  calculate  the  space  that  will  be  saved,  before  actually  doing  the  com¬ 
bining. 

-csid-list 

Include  the  indicated  list  of  deltas.  All  other  deltas  are  omitted,  sid-list  is  a  comma-separated  list 
of  SCCS  delta  IDs  (SIDs).  To  specify  a  range  of  deltas,  use  a  separator  instead  of  a  comma, 
between  two  SIDs  in  the  list. 

-pSID  The  SID  of  the  oldest  delta  to  be  preserved. 

FILES 

s.  COMB  reconstructed  SCCS  file 

comb?????  temporary  file 

SEE  ALSO 

sccs(l),  sccs-admin(l),  sccs-cdc(l),  sccs-delta(l),  sccs-help(l),  sccs-prs(l),  sccs-prt(l),  sccs-rmdel(l), 
sccs-sccsdiff(l),  what(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (sccs-help(l)). 

BUGS 

comb  may  rearrange  the  shape  of  the  tree  of  deltas.  It  may  not  save  any  space;  in  fact,  it  is  possible  for  the 
reconstructed  file  to  actually  be  larger  than  the  original. 
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NAME 

sccs-delta,  delta  -  make  a  delta  to  an  SCCS  file 
SYNOPSIS 

/usr/sccs/delta  [  -nps  ]  [  -gsid-list  ]  [  -mmr-list  ]  [  -rsid  ]  [  -y  [comment]  ]  s. file  name  . . . 

DESCRIPTION 

delta  checks  in  a  record  of  the  line-by-line  differences  made  to  a  checked-out  version  of  a  file  under  SCCS 
control.  These  changes  are  taken  from  the  writable  working  copy  that  was  retrieved  using  the  SCCS  get 
command  (see  sccs-get(l)).  This  working  copy  does  not  have  the  ‘s.’  prefix,  and  is  also  referred  to  as  a 
g-file. 

If  a  directory  name  is  used  in  place  of  the  s filename  ^  argument,  the  delta  command  applies  to  all  s.files  in 
that  directory.  Unreadable  s.files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The 
use  of  as  the  s filename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard  in¬ 
put,  one  s.file  per  line  (requires  -y,  and  in  some  cases,  -in). 

delta  may  issue  prompts  on  the  standard  output  depending  upon  the  options  specified  and  the  flags  that  are 
set  in  the  s.file  (see  sccs-admin(l),  and  the  -m  and  -y  options  below,  for  details). 

OPTIONS 

-n  Retain  the  edited  g-file,  which  is  normally  removed  at  the  completion  of  processing. 

-p  Display  line-by-line  differences  (in  diff(l)  format)  on  the  standard  output. 

-s  Silent.  Do  not  display  warning  or  confirmation  messages.  Do  not  suppress  error  messages  (which 
are  written  to  standard  error). 

-gsid-list 

Specify  a  list  of  deltas  to  omit  when  the  file  is  accessed  at  the  SCCS  version  ID  (SID)  created  by 
this  delta,  siddist  is  a  comma-separated  list  of  SIDs.  To  specify  a  range  of  deltas,  use  a  separa¬ 
tor  instead  of  a  comma,  between  two  SIDs  in  the  list. 

-m  [mrdist] 

If  the  SCCS  file  has  the  v  flag  set  (see  sccs-admiii(l)),  you  must  supply  one  or  more  Modification 
Request  (MR)  numbers  for  the  new  delta.  When  specifying  more  than  one  MR  number  on  the 
command  line,  mr-list  takes  the  form  of  a  quoted,  space-separated  list.  If  -m  is  not  used  and  the 
standard  input  is  a  terminal,  delta  prompts  with  MRs?  for  the  list  (before  issuing  the  comments? 
prompt).  If  the  v  flag  in  the  s.file  has  a  value,  it  is  taken  to  be  the  name  of  a  program  to  validate 
the  MR  numbers.  If  that  validation  program  returns  a  non-zero  exit  status,  delta  terminates 
without  checking  in  the  changes. 

-rsid  When  two  or  more  versions  are  checked  out,  specify  the  version  to  check  in.  This  SID  value  can 
be  either  the  SID  specified  on  the  get  command  line,  or  the  SID  of  the  new  version  to  be  checked 
in  as  reported  by  get.  A  diagnostic  results  if  the  specified  SID  is  ambiguous,  or  if  one  is  required 
but  not  supplied. 

-y[comment] 

Supply  a  comment  for  the  delta  table  (version  log).  A  null  comment  is  accepted,  and  produces  an 
empty  commentary  in  the  log.  If  -y  is  not  specified  and  the  standard  input  is  a  terminal,  delta 
prompts  with  ‘comments?’.  An  unescaped  NEWLINE  terminates  the  comment. 

FILES 


Afile 

temporary  file  of  differences 

^file 

lock  file  for  a  checked-out  version 

temporary  file 

s.file 

SCCS  history  file 

xfile 

temporary  copy  of  the  s.file 

zfile 

temporary  file 
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WARNINGS 

Lines  beginning  with  an  ASCH  SOH  character  (binary  (X)l)  cannot  be  placed  in  the  SCCS  file  unless  the  SOH 
is  escaped.  This  character  has  special  meaning  to  SCCS  (see  sccsfile(5))  and  produces  an  error. 

SEE  ALSO 

sccs(l),  sc€s-admin(l),  sccs-cdc(l),  sccs-get(l),  sccs-help(l),  sccs-prs(l),  sccs-prt(l)»  sccs-rmdel(l), 
sccs>sccsdiff(l),  sccs-unget(l),  what(l),  sccsfile(5) 

Programming  Utilities  andLibraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (sccs-help(l)). 
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NAME 

sccs-get,  get  -  retrieve  a  version  of  an  SCCS  file 

SYNOPSIS 

/usr/sccs/get  [  -begkmnpst  ]  [  -I  [  p  ]  ]  [  -asequence  ]  [  -^date-time  ]  [  -Gg-file  ]  [  -\sid4ist  ]  [  -xsid  ] 

[  -xsid-Ust  ]  s.fiiename  . . . 

DESCRIPTION 

get  retrieves  a  working  copy  from  the  SCCS  history  file,  according  to  the  specified  options. 

For  each  s.fiiename  argument,  get  displays  the  SCCS  delta  ID  (SID)  and  number  of  lines  retrieved. 

If  a  directory  name  is  used  in  place  of  the  s.fiiename  argument,  the  get  command  applies  to  all  s.files  in  that 
directory.  Unreadable  s,files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The  use  of 
as  the  s.fiiename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard  input,  one 
s.file  per  line. 

The  retrieved  file  normally  has  the  same  filename  base  as  the  s.file,  less  the  prefix,  and  is  referred  to  as  the 
g-file. 

For  each  file  processed,  get  responds  (on  the  standard  output)  with  the  SID  being  accessed,  and  with  the 
number  of  lines  retrieved  from  the  s.file. 

OPTIONS 

-b  Create  a  new  branch.  Used  with  the  -e  option  to  indicate  that  the  new  delta  should  have  an  SID  in 
a  new  branch.  Instead  of  incrementing  the  level  for  version  to  be  checked  in,  get  indicates  in  the 
p.file  that  the  delta  to  be  checked  in  should  either  initialize  a  new  branch  and  sequence  (if  there  is 
no  existing  branch  at  the  current  level),  or  increment  the  branch  component  of  the  SID.  If  the  b 
flag  is  not  set  in  the  s.file,  this  option  is  ignored. 

-e  Retrieve  a  version  for  editing.  With  this  option,  get  places  a  lock  on  the  s.file,  so  that  no  one  else 
can  check  in  changes  to  the  version  you  have  checked  out.  If  the  j  flag  is  set  in  the  s.file,  the  lock 
is  advisory;  get  issues  a  warning  message.  Concurrent  use  of  ‘get  -e’  for  different  SIDs  is  al¬ 
lowed,  however,  get  will  not  check  out  a  version  of  the  file  if  a  writable  version  is  present  in  the 
directory.  All  SCCS  file  protections  stored  in  the  s.file,  including  the  release  ceiling,  floor,  and  au¬ 
thorized  user  list,  are  honored  by  ‘get  -e’. 

-g  Get  the  SCCS  version  ID,  without  retrieving  the  version  itself.  Used  to  verify  the  existence  of  a 
particular  SID. 

-k  Suppress  expansion  of  ID  keywords,  -k  is  implied  by  the  -e. 

-m  Precede  each  retrieved  line  with  the  SID  of  the  delta  in  which  it  was  added  to  the  file.  The  SID  is 

separated  from  the  line  with  a  TAB. 

-n  Precede  each  line  with  the  %M%  ID  keyword  and  a  TAB.  When  both  the  -m  and  -n  options  are 
used,  the  ID  keyword  precedes  the  SID,  and  the  line  of  text. 

-p  Write  the  text  of  the  retrieved  version  to  the  standard  output.  All  messages  that  normally  go  to  the 

standard  output  are  written  to  the  standard  error  instead. 

-s  Suppress  all  output  normally  written  on  the  standard  output.  However,  fatal  error  messages 
(which  always  go  to  the  standard  error)  remain  unaffected. 

-t  Retrieve  the  most  recently  created  (top)  delta  in  a  given  release  (for  example:  -rl). 

~l  [  p  ]  Retrieve  a  summary  of  the  delta  table  (version  log)  and  write  it  to  a  listing  file,  with  the  ‘1.’  prefix 

(called  ‘l.file’).  When  -Ip  is  used,  write  the  summary  onto  the  standard  output. 

-a  sequence 

Retrieve  the  version  corresponding  to  the  indicated  delta  sequence  number.  This  option  is  used 
primarily  by  the  SCCS  comb  command  (see  sccs-comb(l));  for  users,  -r  is  an  easier  way  to  speci¬ 
fy  a  version,  -a  supercedes  -r  when  both  are  used. 
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-cdate-time 

Retrieve  the  latest  version  checked  in  prior  to  the  date  and  time  indicated  by  the  date-time  argu¬ 
ment  date-time  takes  the  form:  yy{mm{dd\hh{mm[ss]]]]\  Units  omitted  from  the  indicated 
date  and  time  default  to  their  maximum  possible  values;  that  is  -c7502  is  equivalent  to 
-C750228235959.  Any  number  of  non-numeric  characters  may  separate  the  various  2  digit  com¬ 
ponents.  If  white-space  characters  occur,  the  date-time  specification  must  be  quoted. 

-Gnewname 

Use  newname  as  the  name  of  the  retrieved  version. 

-isid-list 

Specify  a  list  of  deltas  to  include  in  the  retrieved  version.  The  included  deltas  are  noted  in  the 
standard  output  message,  sid-list  is  a  comma-separated  list  of  SIDs.  To  specify  a  range  of  deltas, 
use  a  separator  instead  of  a  comma,  between  two  SIDs  in  the  list. 

~Tsid  Retrieve  the  version  corresponding  to  the  indicated  SID  (delta). 

The  SID  for  a  given  delta  is  a  number,  in  Dewey  decimal  format,  composed  of  two  or  four  fields: 
the  release  and  level  fields,  and  for  branch  deltas,  the  branch  and  sequence  fields.  For  instance,  if 
1.2  is  the  SID,  1  is  the  release,  and  2  is  the  level  number.  If  1.2.3.4  is  the  SID,  3  is  the  branch  and 
4  is  the  sequence  number. 

You  need  not  specify  the  entire  SID  to  retrieve  a  version  with  get.  When  you  omit  -r  altogether, 
or  when  you  omit  both  release  and  level,  get  normally  retrieves  the  highest  release  and  level.  If 
the  d  flag  is  set  to  an  SID  in  the  s.file  and  you  omit  the  SID,  get  retrieves  the  default  version  indi¬ 
cated  by  that  flag. 

When  you  specify  a  release  but  omit  the  level,  get  retrieves  the  highest  level  in  that  release.  If 
that  release  does  not  exist,  get  retrieves  highest  level  from  the  next-highest  existing  release. 

Similarly  with  branches,  if  you  specify  a  release,  level  and  branch,  get  retrieves  the  highest  se¬ 
quence  in  that  branch. 

-xsid-list 

Exclude  the  indicated  deltas  from  the  retrieved  version.  The  excluded  deltas  are  noted  in  the  stan¬ 
dard  output  message,  sid-list  is  a  comma-separated  list  of  SIDs.  To  specify  a  range  of  deltas,  use  a 
separator  instead  of  a  comma,  between  two  SIDs  in  the  list. 

USAGE 

ID  Keywords 

In  the  absence  of  -e  or  -k,  get  expands  the  following  ID  keywords  by  replacing  them  with  the  indicated 
values  in  the  text  of  the  retrieved  source. 

Keyword  Value 

%  A%  Shorthand  notation  for  an  ID  line  with  data  for  what(l):  %Z%  %  Y%  %M%  %I%  %Z% 

%  B  %  SID  branch  component 

% C %  Current  line  number.  Intended  for  identifying  messages  output  by  the  program  such  as  "'this 

shouldn’ t  have  happened^'  type  errors.  It  is  not  intended  to  be  used  on  every  line  to  provide 
sequence  numbers. 

%D  %  Current  date:  yylmmidd 

% E %  Date  newest  applied  delta  was  created:  yylmmidd 

%F%  sees  s.file  name 

% G%  Date  newest  applied  delta  was  created;  mmiddlyy 

%H%  Current  date:  mm/rfd/yy 

%I%  SID  of  the  retrieved  version:  %R%.%L%.%B%.%S% 

%  L  %  SID  level  component 

%1VI%  Module  name:  either  the  value  of  the  m  flag  in  the  s.file  (see  sccs-admin(l)},  or  the  name  of 
the  s.file  less  the  prefix 
%P%  Fully  qualified  s.file  name 
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%Q%  Value  of  the  q  flag  in  the  s.flle 
%  R  %  SID  Release  component 

%  S  %  SID  Sequence  component 

%T%  CuTTGiit  time:  hhtmmiss 

%U%  Time  the  newest  applied  delta  was  created:  hh  :mm  :ss 
% W %  Shorthand  notation  for  an  ID  line  with  data  for  what:  %Z%  %M%  %l% 

%Y %  Module  type:  value  of  the  t  flag  in  the  s.file 

%Z%  4-character  string:  *<6)(#)’,  recognized  by  what. 

FILES 

“g-file*» 

Ifile 
pfile 
z.file 

SEE  ALSO 

sccs(l),  sccs-admin(l),  sccs-delta(l),  sccs-help(l),  sccs-prs(l),  sccs-prt(l),  sccs-sact(l),  sccs-unget(l), 
what(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (sccs-help(l)). 

BUGS 

If  the  effective  user  has  write  permission  (either  explicitly  or  implicitly)  in  the  directory  containing  the 
SCCS  files,  but  the  real  user  does  not,  only  one  file  may  be  named  when  using  -e. 


version  retrieved  by  get 
file  containing  extracted  delta  table  info 
permissions  (lock)  file 
temporary  copy  of  sjile 
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/  NAME 

_ J  sccs-help,  help  -  ask  for  help  regarding  SCCS  error  or  warning  messages 

SYNOPSIS 

/usr/sccs/help  [  argument  ] . . . 

DESCRIPTION 

help  retrieves  information  to  further  explain  errors  messages  and  warnings  from  SCCS  commands.  It  also 
provides  some  information  about  SCCS  command  usage.  If  no  arguments  are  given,  help  prompts  for  one. 

An  argument  may  be  a  message  number  (which  normally  appears  in  parentheses  following  each  SCCS  er¬ 
ror  or  warning  message),  or  an  SCCS  command  name,  help  responds  with  an  explanation  of  the  message 
or  a  usage  line  for  the  command. 

When  all  else  fails,  try  Vusr/sccs/help  stuck’. 

FILES 

/usr/lib/help  directory  containing  files  of  message  text. 

/usr/sccs/help 

SEE  ALSO 

sccs(l),  sccs-admin(l),  sccs-cdc(l),  sccs-comb(l),  sccs-delta(l),  sccs-get(l),  sccs-prs(l),  sccs-prt(l), 
sccs-rmdel(l),  sccs-sact(l),  sccs-sccsdiff(l),  sccs-unget(l),  sccs-val(l),  what(l),  sccsfile(5) 
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NAME 

sccs-prs,  prs  -  display  selected  portions  of  an  SCCS  history 
SYNOPSIS 

/usr/sccs/prs  [  -ael  ]  [  -cdate-time  ]  [  -ddataspec  ]  [  -rsid  ]  s. filename . . . 

DESCRIPTION 

prs  displays  part  or  all  of  the  SCCS  file  (see  sccsifile(5))  in  a  user  supplied  format. 

If  a  directory  name  is  used  in  place  of  the  s filename  argument,  the  prs  command  applies  to  all  s.files  in 
that  directory.  Unreadable  s.files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The 
use  of  as  the  s filename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard 
input,  one  s.file  per  line. 

OPTIONS 

In  the  absence  of  options,  prs  displays  the  delta  table  (version  log).  In  the  absence  of  -d,  or  -1,  prs 
displays  the  entry  for  each  delta  indicated  by  the  other  options. 

-a  Include  all  deltas,  including  those  marked  as  removed  (see  sccs-rmdel(l)), 

-e  Request  information  for  all  deltas  created  earlier  than,  and  including,  the  delta  indicated  with  -r 
or  ~c. 

-1  Request  information  for  all  deltas  created  later  than,  and  including,  the  delta  indicated  with  -r  or 

“C. 

-cdate-time 

Display  information  on  the  latest  delta  checked  in  prior  to  the  date  and  time  indicated  by  the  date¬ 
time  argument,  date-time  takes  the  form; 
yy[mm[dd[hh[mm[ss]  ]  ]  ]  ] 

Units  omitted  from  the  indicated  date  and  time  default  to  their  maximum  possible  values;  that  is 
-c7502  is  equivalent  to  -c750228235959.  Any  number  of  non-numeric  characters  may  separate 
the  various  2  digit  components.  If  white-space  characters  occur,  the  date-time  specification  must 
be  quoted. 

-ddataspec 

Produce  a  report  according  to  the  indicated  data  specification,  dataspec  consists  of  a  (quoted)  text 
string  that  includes  embedded  data  keywords  of  the  form:  ':key:'  (see  Data  Keywords,  below), 
prs  expands  these  keywords  in  the  output  it  produces.  To  specify  a  TAB  character  in  the  output, 
use  \t;  to  specify  a  NEWLINE  in  the  output,  use  \n. 

-rsid  Specify  the  SCCS  delta  ID  (SID)  of  the  delta  for  which  information  is  desired.  If  no  SID  is 
specified,  the  most  recently  created  delta  is  used. 

USAGE 

Data  Keywords 

Data  keywords  specify  which  parts  of  an  SCCS  file  are  to  be  retrieved.  All  parts  of  an  SCCS  file  (see 
sccsfile(5))  have  an  associated  data  keyword.  A  data  keyword  may  appear  any  number  of  times  in  a  data 
specification  argument  to  -d.  These  data  keywords  are  listed  in  the  table  below: 


Keyword 

Data  Item 

File 

Section 

Value 

Format** 

:A: 

a  format  for  the  what  sti-ing: 

N/A 

:Z::Y;  :M:  ;I::Z: 

S 

;B: 

branch  number 

D 

nnnn 

S 

:BD; 

body 

B 

text 

M 

:BF; 

branch  flag 

F 

yes  or  no 

S 

:CB: 

ceiling  boundary 

F 

;R: 

S 

:C: 

comments  for  delta 

D 

text 

M 

:D: 

date  delta  created 

D 

:Dy:/;Dm:/:Dd: 

S 

:Dd: 

day  delta  created 

D 

nn 

s 

W' 
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(  i 


:Dg: 

:DI: 

deltas  ignored  (seq  #) 
seq-no.  of  deltas  included. 

D 

:DS:  :DS:.,. 

S 

excluded,  ignored 

D 

:Dn:/:Dx;/:Dg: 

S 

:DL: 

delta  line  statistics 

D 

:Li:/:Ld:/:Lu: 

s 

:Din; 

month  delta  created 

D 

nn 

s 

:Dn: 

deltas  included  (seq  #) 

D 

:DS:  :DS:  .  .. 

s 

:DP: 

predecessor  delta  seq-no. 

D 

nnnn 

s 

:Ds: 

default  SID 

F 

s 

:DS; 

delta  sequence  number 

D 

nnnn 

s 

:Dt: 

delta  information 

D 

:DT;  :I:  :D:  ;T:  :P:  :DS:  :DP: 

s 

:DT: 

delta  type 

D 

D  orR 

s 

:Dx: 

deltas  excluded  (seq  #) 

D 

:DS:  ... 

s 

:Dy: 

year  delta  created 

D 

nn 

s 

:F: 

s.file  name 

N/A 

text 

s 

:FB; 

floor  boundary 

F 

:R: 

s 

:FD: 

file  descriptive  text 

C 

text 

M 

:FL: 

flag  list 

F 

text 

M 

:GB: 

gotten  body 

B 

text 

M 

:I: 

sees  delta  ID  (SID) 

D 

:R:.:L:.:B:.:S: 

S 

:J: 

joint  edit  flag 

F 

yes  or  no 

S 

:KF: 

keyword  error/waming  flag 

F 

yes  or  no 

S 

:L: 

level  number 

D 

nnnn 

s 

:Ld: 

lines  deleted  by  delta 

D 

nnnnn 

S 

:Li: 

lines  inserted  by  delta 

D 

nnnnn 

S 

:LK: 

locked  releases 

F 

:R:... 

s 

:Lu: 

lines  unchanged  by  delta 

D 

nnnnn 

s 

:M: 

module  name 

F 

text 

s 

;MF: 

MR  validation  flag 

F 

yes  or  no 

s 

:MP: 

MR  validation  program 

F 

text 

s 

:MR: 

MR  numbers  for  delta 

D 

text 

M 

:ND: 

null  delta  flag 

F 

yes  or  no 

S 

:Q: 

user  defined  keyword 

F 

text 

S 

:P: 

user  who  created  delta 

D 

username 

s 

:PN: 

s.file’s  pathname 

N/A 

text 

s 

:R: 

release  number 

D 

nnnn 

s 

:S: 

sequence  number 

D 

nnnn 

s 

:T: 

time  delta  created 

D 

;Th;:;Tm:::Ts: 

s 

:Th: 

hour  delta  created 

D 

nn 

s 

:Tin: 

minutes  delta  created 

D 

nn 

s 

:Ts: 

seconds  delta  created 

D 

nn 

s 

:UN: 

user  names 

U 

text 

M 

:W: 

a  form  of  what  string 

N/A 

;Z::M:\t:I: 

s 

:Y: 

module  type  flag 

F 

text 

s 

:Z: 

what  string  delimiter 
*B  =  body,  D  =  delta  table,  F  = 

N/A  (®(#) 

flags,  U  =  user  names 

s 

S  =  simple  format,  M  =  multi-line  format 
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EXAMPLES 

The  command: 

/usr/sccs/prs  -e  -d"  program.c 

produces: 

1.6  username 

1.5  username 


FILES 

/tmp/pr?????  temporary  file 

SEE  ALSO 

sccs(l).  sccs-cdc(l),  sccs-delta(l),  sccs-g€t(l),  sccs-help(l),  sccs-prt(l),  sccs-sact(l),  sccs-sccsdifr(l), 
what(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (sccs-help(l)). 
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NAME 

sccs-prt,  pit  -  display  delta  table  information  from  an  SCCS  file 
SYNOPSIS 

/usr/sccs/prt  [— abdefistu]  [  -cdate-time  ]  [  -xdate-time  ]  [  —ysid  ]  s.filename . . . 

DESCRIPTION 

prt  prints  selected  portions  of  an  SCCS  file.  By  default,  it  prints  the  delta  table  (version  log). 

If  a  directory  name  is  used  in  place  of  the  s.filename  argument,  the  prt  command  applies  to  all  s.files  in  that 
directory.  Unreadable  s.files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The  use  of 
as  the  s.filename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard  input,  one 
s.file  per  line. 

OPTIONS 

If  any  option  other  than  -y,  -c,  or  -r  is  supplied,  the  name  of  each  file  being  processed  (preceded  by  one 
NEWLINE  and  followed  by  two  NEWLINE  characters)  appears  above  its  contents. 

If  none  of  the  — u,  —f,  — t,  or  —b  options  are  used,  — d  is  assumed.  — s,  — i  are  mutually  exclusive,  as  are  ~c 
and-r. 

-a  Display  log  entries  for  all  deltas,  including  those  marked  as  removed. 

-b  Print  the  body  of  the  s.file. 

-d  Print  delta  table  entries.  This  is  the  default. 

-e  Everything.  This  option  implies  -d,  -i,  -u,  -f,  and  ~t. 

-f  Print  the  flags  of  each  named  s.file. 

— i  Print  the  serial  numbers  of  included,  excluded,  and  ignored  deltas. 

-s  Print  only  the  first  line  of  the  dela  table  entries;  that  is,  only  up  to  the  statistics. 

-t  Print  the  descriptive  text  contained  in  the  s.file. 

~u  Print  the  user-names  and/or  numerical  group  IDs  of  users  allowed  to  make  deltas. 

-cdate-time 

Exclude  delta  table  entries  that  are  specified  cutoff  date  and  time.  Each  entry  is  printed  as  a  single 
line,  preceded  by  the  name  of  die  SCCS  file.  This  format  (also  produced  by  -r  ,  and  -y)  makes  it 
easy  to  sort  multiple  della  tables  in  chronological  order.  When  both  ~y  and  -c,  or  -y  and  ~r  are 
supplied,  prt  stops  printing  when  the  first  of  the  two  conditions  is  met. 

-rdate-time 

Exclude  delta  table  entries  that  are  newer  than  the  specified  cutoff  date  and  time. 

-ysid  Exclude  delta  table  entries  made  prior  to  the  SID  specified.  If  no  delta  in  the  table  has  the 
specified  SID,  the  entire  table  is  printed.  If  no  SID  is  specified,  the  most  recent  delta  is  printed. 

USAGE 

Output  Format 

The  following  format  is  used  to  print  those  portions  of  the  s.file  that  are  specified  by  the  various  options. 

•  NEWLINE 

•  Type  of  delta  (D  or  R) 

•  SPACE 

•  SCCS  delta  ID  (SID) 

•  TAB 

•  Date  and  time  of  creation  in  the  form:  yy/mmldd  hhimmiss 
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•  SPACE 

•  Username  the  delta’s  creator 

•  TAB 

•  Serial  number  of  the  delta 

•  SPACE 

•  Predecessor  delta’s  serial  number 

•  TAB 

•  Line-by-line  change  statistics  in  the  form:  insertedfdeletedfunchanged 

•  NEWLINE 

•  List  of  included  deltas,  followed  by  a  NEWLINE  (only  if  there  were  any  such  deltas  and  the  — i 
options  was  used) 

•  List  of  excluded  deltas,  followed  by  a  NEWLINE  (only  if  there  were  any  such  deltas  and  the  -i 
options  was  used) 

•  List  of  ignored  deltas,  followed  by  a  NEWLINE  (only  if  there  were  any  such  deltas  and  the  -i 
options  was  used) 

•  List  of  modification  requests  (MR  s),  followed  by  a  NEWLINE  (only  if  any  MR  numbers  were 
supplied). 

•  Lines  of  the  delta  commentary  (if  any),  followed  by  a  NEWLINE. 

EXAMPLES 

The  command: 

/usr/sccs/prt  -y  program.c 

produces  a  one-line  display  of  the  delta  table  entry  for  the  most  recent  version: 

s.program.c:  D  1.6  88/07/06  21:39:39  username  5  4  00159/00080/00636  . . . 

SEE  ALSO 

sccs(l),  sccs-cdc(l),  sccs-delta(l),  sccs-get(l),  sccs-help(l),  sccs-prs(l),  sccs-sact(l),  sccs-sccsdiff(l), 
what(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (sccs-help(l)). 
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NAME 

sccs-rmdel,  rmdel  -  remove  a  delta  from  an  SCCS  file 
SYNOPSIS 

/usr/sccs/rmdel  -rsid  s.filename  . . . 

DESCRIPTION 

rmdel  removes  the  delta  specified  by  the  SCCS  delta  ID  (SID)  supplied  with  -r.  The  delta  to  be  removed 
must  be  the  most  recent  (leaf)  delta  in  its  branch.  In  addition,  the  SID  must  not  be  that  of  a  version  checked 
out  for  editing:  it  must  not  appear  in  any  entry  of  the  version  lock  file  (p.file). 

If  you  created  the  delta,  or,  if  you  own  the  file  and  directory  and  have  write  permission,  you  can  remove  it 
with  rmdel. 

If  a  directory  name  is  used  in  place  of  the  s.filename  argument,  the  rmdel  command  applies  to  all  s.files  in 
that  directory.  Unreadable  s^files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The 
use  of  as  the  s.filename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard  in¬ 
put,  one  s.file  per  line. 

FILES 

sfile 
zfile 
Vfile 

SEE  ALSO 

sccs(I),  sccs-admin(l),  sccs-cdc(l),  sccs-comb(l),  sccs-delta(l),  sccs-help(l),  sccs-prs(l),  sccs-prt(l), 
sccs-sccsdiff(l),  sccs-unget(l),  what(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (sccs-help(I)). 


history  file 

temporary  copy  of  the  s.file 
permissions  file 
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NAME 

sccs-sact,  sact-  show  editing  activity  status  of  an  SCCS  file 
SYNOPSIS 

/usr/sccs/sact  s.filename  . . . 

DESCRIPTION 

sact  informs  the  user  of  any  SCCS  files  that  are  checked  out  for  editing. 

The  output  for  each  named  file  consists  of  five  fields  separated  by  SPACE  characters. 

•  SID  of  a  delta  that  currently  exists  in  the  SCCS  file,  to  which  changes  will  be  made  to  make  the 
new  delta 

•  SID  for  the  new  delta  to  be  created 

•  Username  of  the  person  who  has  the  file  checked  out  for  editing. 

•  Date  that  the  version  was  checked  ouL 

•  Time  that  the  version  was  checked  out. 

If  a  directory  name  is  used  in  place  of  the  s.filename  argument,  the  sact  command  applies  to  all  s.files  in 
that  directory.  Unreadable  s.files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The 
use  of  as  the  s.filename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard  in¬ 
put,  one  s,file  per  line. 

SEE  ALSO 

sccs(l),  sccs-d€lta(l),  sccs-get(l),  sccs-help(l),  sccs-prs(l),  sccs-prt(l),  what(l),  sccsfile(5) 
Programming  Utilities  and  Libraries 
DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (see  sccs-help(l)). 

BUGS 

sact  is  not  recognized  as  a  subcommand  of  sccs(l). 


478 


Last  change:  30  June  1988 


Sun  Release  4.1 


SCCS‘SCCSDIFF(1) 


USER  COMMANDS 


SCCS-SCCSDIFF(l) 


NAME 

sccs-sccsdiff,  sccsdiff-  compare  two  versions  of  an  SCCS  file 
SYNOPSIS 

/usr/sccs/sccsdilT  [  -p  ]  -rsid  -rsid  [  dijf-options  ]  s. filename 
DESCRIPTION 

sccsdiff  compares  two  versions  of  an  SCCS  file  and  displays  the  differences  between  the  two  versions.  Any 
number  of  SCCS  files  may  be  specified;  the  options  specified  apply  to  all  named  s.files. 

OPTIONS 

-p  Pipe  output  for  each  file  through  pr(lV). 

-rsid  Specify  a  version  corresponding  to  the  indicated  SCCS  delta  ID  (SID)  for  comparison.  Versions 
are  passed  to  diff(l)  in  the  order  given. 

diff-options 

Pass  options  to  diff(l),  including:  -c,  -e,  ~f,  -h,  -b  and  -D. 

FILES 

/tmp/get?????  temporary  files 

SEE  ALSO 

diff(l),  sccs(l),  sccs-delta(l),  sccs-get(l),  sccs-help(l),  sccs-prs(l),  sccs-prt(l),  what(l),  sccsfile(5) 
Programming  Utilities  and  Libraries 

DIAGNOSTICS 

filename:  No  differences 

If  the  two  versions  are  the  same. 

Use  the  SCCS  help  command  for  explanations  of  other  messages  (see  sccs-help(l)). 


Sun  Release  4.1 


Last  change:  30  June  1988 


479 


SCCS-UNGET(l) 


USER  COMMANDS 


SCCS-UNGET(l) 


NAME 

sccs-unget,  unget  -  undo  a  previous  get  of  an  SCCS  file 
SYNOPSIS 

/usr/sccs/unget  [  -ns  ]  [  ~Tsid  ]  s.filename  . . . 

DESCRIPTION 

unget  undoes  the  effect  of  a  ‘get  -e’  done  prior  to  the  creation  of  the  pending  delta. 

If  a  directory  name  is  used  in  place  of  the  s.filename  argument,  the  unget  command  applies  to  all  s.files  in 
that  directory.  Unreadable  s.files  produce  an  error;  processing  continues  with  the  next  file  (if  any).  The 
use  of  as  the  s.filename  argument  indicates  that  the  names  of  files  are  to  be  read  from  the  standard  in¬ 
put,  one  s.file  per  line. 

OPTIONS 

-n  Retain  the  retrieved  version,  which  is  otherwise  removed. 

-s  Suppress  display  of  the  SCCS  delta  ID  (SID). 

-Tsid  When  multiple  versions  are  checked  out,  specify  which  pending  delta  to  abort.  A  diagnostic 
results  if  the  specified  SID  is  ambiguous,  or  if  it  is  necessary  but  omitted  from  the  command  line. 

SEE  ALSO 

sccs(l),  sccs-delta(l),  sccs-get(l),  sccs-help(l),  sccs-prs(l),  sccs-prt(l),  sccs-rmdel(l),  sccs-sact(l), 
sccs-sccsdiff(l),  what(l),  sccsfile(5) 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (see  sccs-help(l)). 
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NAME 

sccs-val,  val  -  validate  an  SCCS  file 

SYNOPSIS 

/usr/sccs/val  - 

/usr/sccs/val  [  -s  ]  [  ~m  name  ]  [  -rsid  ]  [  -y  type  ]  s. filename  . . . 

DESCRIPTION 

val  determines  if  the  specified  s.files  files  meet  the  characteristics  specified  by  the  indicated  arguments,  val 
can  process  up  to  50  files  on  a  single  command  line. 

val  has  a  special  argument,  which  reads  the  standard  input  until  the  end-of-file  condition  is  detected. 
Each  line  read  is  independently  processed  as  if  it  were  a  command  line  argument  list. 

val  generates  diagnostic  messages  on  the  standard  output  for  each  command  line  and  file  processed  and 
also  returns  a  single  8“bit  code  upon  exit  as  described  below. 

The  8-bit  code  returned  by  val  is  a  disjunction  of  the  possible  errors,  that  is,  it  can  be  interpreted  as  a  bit 
string  where  (moving  from  left  to  right)  the  bits  set  are  interpreted  as  follows: 

bit  0  =  missing  file  argument 

bit  1  =  unknown  or  duplicate  option 

bit  2  =  corrupted  s.file 

bit  3  =  can  not  open  file  or  file  not  in  s.file  format 

bit  4  =  the  SCCS  delta  ID  (SID)  is  invalid  or  ambiguous 

bit  5  =  the  SID  does  not  exist 

bit  6  =  mismatch  between  %Y  %  and  — y  argument 

bit  7  =  mismatch  between  %M%  -m  argument 

val  can  process  two  or  more  files  on  a  given  command  line,  and  in  turn  can  process  multiple  command 
lines  (when  reading  the  standard  input).  In  these  cases,  an  aggregate  code  is  returned  which  is  the  logical 
OR  of  the  codes  generated  for  each  command  line  and  file  processed. 

OPTIONS 

-s  Silent.  Suppress  the  normal  error  or  warning  messages. 

-mname  Compare  name  with  the  %M%  ID  keyword  in  the  s.file. 

-rsid  Check  to  see  if  the  indicated  SID  is  ambiguous,  invalid,  or  absent  from  the  s.file. 

-y  type  Compare  type  with  the  % Y%  ID  keyword. 

SEE  ALSO 

sccs(l),  s€cs-admiii(l),  sccs-delta(l),  sccs-get(l),  sccs-help(l),  what(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 
DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (see  sccs-help(l)). 
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NAME 

screenblank  —  turn  off  the  screen  when  the  mouse  and  keyboard  are  idle 
SYNOPSIS 

screenblank  [  ~m  ]  [  -k  ]  [  -d  interval  ]  [  --e  interval  ]  [  -f frame-bi^er  ] 

DESCRIPTION 

screenblank  turns  off  the  display  when  the  mouse  and  keyboard  are  idle  for  an  extended  period  (the  de¬ 
fault  is  10  minutes),  screenblank  will  continue  to  run  until  killed  by  hand,  using  ‘kill  processid\ 

Place  the  screenblank  command  in  your  /etc/rcJocai  file. 

OPTIONS 

-m  Do  not  check  whether  the  mouse  has  been  idle. 

— k  Do  not  check  whether  the  keyboard  has  been  idle. 

-d  interval 

Disable  after  interval  seconds,  interval  is  a  number  of  the  form  xxxjcxx  where  each  x  is  a  decimal 
digit.  The  default  is  600  seconds  (10  minutes). 

-e  interval 

Enable  within  interval  seconds,  interval  is  the  time  between  successive  polls  for  keyboard  or 
mouse  activity.  If  a  poll  detects  keyboard  or  mouse  activity,  the  display  is  resumed,  interval  is  a 
number  of  seconds,  of  the  form  xxxjcxx  where  each  x  is  a  decimal  digit.  The  default  is  0.25 
seconds. 

-f frame-buffer 

frame-buffer  is  the  path  name  of  the  frame-buffer  on  which  video  disabling/enabling  applies.  The 
defaults  is  /dev/fb. 

FILES 

/dev/fb 
SEE  ALSO 

lockscreen(l),  sunview(l) 

BUGS 

screenblank  only  checks  /dev/console  for  activity;  it  does  not  check  non-window  programs  from  /dev/tty 
which  bypass  /dev/console  .  Consequently,  screenblank  will  turn  off  the  display  if /dev/tty  programs  (for 
example,  pixrect-based  programs)  are  the  only  ones  running. 

When  not  running  sunview(l),  only  the  RETURN  key  resumes  video  display. 
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NAME 

screendump  -  dump  a  frame-buffer  image  to  a  file 
SYNOPSIS 

screendump  [  -cCeo  ]  [  -f frame-buffer  ]  [  -t  type  ]  [  -xyXY  value  ]  [filename  ] 

DESCRIPTION 

screendump  reads  the  contents  of  a  frame  buffer  and  writes  the  display  image  to  filename  (the  default  is 
the  standard  output )  in  Sun  standard  rasterfile  format. 

If  the  frame  buffer  has  both  an  overlay  plane  and  color  planes,  screendump  examines  the  overlay  enable 
plane  and  tries  to  make  the  output  file  represent  what  is  visible  on  the  screen.  It  maps  the  overlay  plane 
foreground  and  background  colors  into  the  closest  values  present  in  the  color  map  for  the  color  planes. 

OPTIONS 
-C 


-C 

-e 

-o 

”f frame-buffer 

-t  type 

-X  value 
-y  value 

-X  value 
-Y  value 

EXAMPLES 

The  command: 

example%  screendump  $ave.this.image 

writes  the  current  contents  of  the  console  frame  buffer  into  the  file  save.this.image, 
while  the  command: 

example  %  screendump  -f  /dev/cgtwo  save.color. image 
writes  the  current  contents  of  the  color  frame  buffer  /dev/cgtwo  into  the  file  savexolor. image. 

The  command: 

example  %  screendump  \  Ipr  -Pversatec  -v 

sends  a  rasterfile  containing  the  current  frame-buffer  to  the  lineprinter,  selecting  the  printer  versatec  and 
the  V  output  filter  (see  /etc/printcap),  The  printer  must  support  an  appropriate  imaging  model  such  as 
PostScript  in  order  to  print  the  image. 

FILES 

/usr/lib/rasfilters/+  filters  for  non-standard  rasterfile  formats 

/dev/fb  default  frame  buffer  device 

/etc/printcap 


Dump  the  frame-buffer  contents  directly  without  making  a  temporary  copy  in  a  memory 
pixrect.  Saves  time  and  memory  but  lengthens  the  time  the  frame-buffer  must  be  inac¬ 
tive  to  guarantee  a  consistent  screen  dump. 

Dump  the  frame-buffer  color  planes  only  (ignored  if  the  display  does  not  have  color 
planes). 

Set  the  output  rasterfile  type  to  2,  RT_BYTE_ENCODED.  For  most  images  this  saves  a 
significant  amount  of  space  compared  to  the  standard  format. 

Dump  the  frame-buffer  overlay  plane  only  (ignored  if  the  display  does  not  have  an  over¬ 
lay  plane). 

Dump  the  specified  frame-buffer  device  (default  is  /dev/fb). 

Set  the  output  rasterfile  type  (default  1,  RT„STANDARD). 

Set  the  X  or  y  coordinate  of  the  upper  left  comer  of  the  area  to  be  dumped  to  the  given 
value. 

Set  the  width  or  height  of  the  area  to  be  dumped  to  the  given  value. 
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SEE  ALSO 

Ipr(l),  rasfilter8tol(l),  rastrepl(l).  screenload(l) 

Pixrect  Reference  Manual 

BUGS 

The  output  file  or  the  screen  may  be  corrupted  if  the  frame-buffer  contents  are  modified  while  the  dump  is 
in  progress. 


484 


Last  change:  8  September  1988 


Sun  Release  4.1 


SCREENLOAD(l) 


USER  COMMANDS 


SCREENLOAD(l) 


NAME 

screenload  --  load  a  frame-buffer  image  from  a  file 

SYNOPSIS 

screenload  [  -bgnw  ]  [  -dopr  ]  [  -(frame-buffer  ]  [  -h  count  data  . . .  ]  [  -i  color  ]  [  -xyXY  value  ] 
[filename  ] 

DESCRIPTION 

screenload  reads  a  Sun  standard  rasterfile  (see  rasterfile(5))  and  displays  it  on  a  frame-buffer,  screenload 
is  able  to  display  monochrome  images  on  a  color  display,  but  cannot  display  color  images  on  a  mono¬ 
chrome  display.  If  the  input  file  contains  a  color  image,  a  frame-buffer  has  not  been  explicitly  specified, 
and  /dev/fb  is  a  monochrome  frame-buffer,  screenload  looks  for  a  color  frame-buffer  with  one  of  the  stan¬ 
dard  device  names. 

If  the  image  contained  in  the  input  file  is  larger  than  the  actual  resolution  of  the  display,  screenload  clips 
the  right  and  bottom  edges  of  the  image.  If  the  input  image  is  smaller  than  the  display  (for  example,  load¬ 
ing  an  1152-by-900  image  on  a  1600-by-1280  high  resolution  display),  screenload  centers  the  image  on 
the  display  surface  and  fills  the  border  area  with  solid  black  (by  default).  Various  options  may  be  used  to 
change  the  image  location,  or  to  change  or  disable  the  fill  pattern. 

OPTIONS 

-b  Fill  the  border  area  with  a  pattern  of  solid  ones  (default).  On  a  monochrome  display  this 

results  in  a  black  border;  on  a  color  display  the  color  map  value  selected  by  the  -i  option 
determines  the  border  color. 

-g  Fill  the  border  area  with  a  pattern  of  "desktop  grey”.  On  a  monochrome  display  this 

results  in  a  border  matching  the  default  background  pattern  used  by  SunView;  on  a  color 
display  the  color  map  value  selected  by  the  -i  option  determines  the  foreground  border 
color,  though  the  pattern  is  the  same  as  on  a  monochrome  display. 

-n  Do  not  fill  the  border  area. 

-w  Fill  the  border  area  with  a  pattern  of  solid  zeros.  On  a  monochrome  display  this  results 

in  a  white  border;  on  a  color  display  the  color  map  value  at  index  0  determines  the  bord¬ 
er  color, 

-d  Print  a  warning  message  if  the  display  size  does  not  match  the  rasterfile  image  size. 

-o  Load  the  image  on  the  overlay  plane  of  the  display  (ignored  if  the  display  does  not  have 

an  overlay  plane). 

-p  Wait  for  a  NEWLINE  to  be  typed  on  the  standard  input  before  exiting. 

-r  Reverse  the  foreground  and  background  of  the  output  image.  Useful  when  loading  a 

screendump  made  from  a  reverse  video  screen. 

-(frame-buffer  Display  the  image  on  the  specified  frame-buffer  device  (default  /dev/fb). 

-h  count  data . . .  Fill  the  border  area  with  the  bit  pattern  described  by  the  following  count  16-bit  hexade¬ 
cimal  constants.  Note:  a  "1”  bit  is  black  and  a  “0”  bit  is  white  on  the  monochrome 
display;  on  a  color  display  the  color  map  value  selected  by  the  -i  option  determines  the 
border  foreground  color.  The  number  of  hex  constants  in  the  pattern  is  limited  to  16. 

-i  color  Fill  the  border  area  with  the  given  color  value  (default  255). 

-x  value 

-y  value  Set  the  x  or  y  coordinate  of  the  upper  left  comer  of  the  image  on  the  display  to  the  given 

value. 
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“X  value 

— Y  value  Set  the  maximum  width  or  height  of  the  displayed  image  to  the  given  value. 

EXAMPLES 

The  command: 

example  %  screenload  saved.display.image 

loads  the  raster  image  contained  in  the  file  saved.display .image  on  the  display  type  indicated  by  the 
rasterfile  header  in  that  file. 

The  command: 

example%  screenload  -f  /dev/cgtwo  mono€hrome.image 
reloads  the  raster  image  in  the  file  monochrome.image  on  the  color  frame-buffer  device  /dev/cgtwo. 

The  command: 

example  %  screenload  -hi  ffff  small.saved.image 
is  equivalent  to  the  -b  option  (fill  border  with  black),  while 

example%  screenload  -h4  8888  8888  2222  2222  small.saved.image 
is  equivalent  to  the  -g  option  (fill  border  with  desktop  grey). 

FILES 

/usr/lib/rasfilters/*  filters  for  non-standard  rasterfile  formats 

/dev/fb  default  frame  buffer  device 

SEE  ALSO 

rasfilter8tol(l),  rastrepl(l),  screendump(l),  screenload(l) 

Pixrect  Reference  Manual 
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NAME 

script  -  make  typescript  of  a  terminal  session 
SYNOPSIS 

script  [  ”3  ]  [filename  ] 

DESCRIPTION 

script  makes  a  typescript  of  everything  printed  on  your  terminal.  The  typescript  is  written  \o  filename,  or 
appended  to  filename  if  the  -a  option  is  given.  It  can  be  sent  to  the  line  printer  later  with  Ipr(l).  If  no  file 
name  is  given,  the  typescript  is  saved  in  the  file  typescript. 

The  script  ends  when  the  forked  shell  exits. 

OPTIONS 

—a  Append  the  script  to  the  specified  file  instead  of  writing  over  it. 

SEE  ALSO 

Ipr(l) 

BUGS 

script  places  everything  in  the  log  file.  This  is  not  what  the  naive  user  expects. 
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NAME 

sdiff-  contrast  two  text  files  by  displaying  them  side-by-side 
SYNOPSIS 

sdiff  [  -1  ]  [  -o  outfile  ]  [  -s  ]  [  -w  n  ]  filenamel  filename! 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

Sdiff  uses  the  output  of  diff-b  to  produce  a  side-by-side  listing  of  two  files  indicating  those  lines  that  are 
different  Each  line  of  the  two  files  is  printed  with  a  blank  gutter  between  them  if  the  lines  are  identical,  a 
<  in  the  gutter  if  the  line  only  exists  in  filenamel ,  a  >  in  the  gutter  if  the  line  only  exists  in  filename! ,  and  a 
I  for  lines  that  are  different.  See  EXAMPLES. 

OPTIONS 

-w  n  Use  «  as  the  width  of  the  output  line.  The  default  line  length  is  130  characters. 

-I  Only  print  the  left  side  of  any  identical  lines. 

-s  Silent.  Do  not  print  identical  lines. 

-0  outfile 

Use  the  next  argument,  output,  as  the  name  of  an  output  file  created  as  an  interactively  controlled 
merging  of  filenamel  and  filename!.  Identical  lines  of  filenamel  and  filename!  are  copied  to  out¬ 
put.  Sets  of  differences,  as  produced  by  diff,  are  printed;  where  a  set  of  differences  share  a  com¬ 
mon  gutter  character.  After  printing  each  set  of  differences,  sdiff  prompts  with  a  %  and  waits  for 
you  to  type  one  of  the  following  commands: 

1  Append  the  left  column  to  the  output  file. 

r  Append  the  right  column  to  the  output  file. 

s  Turn  on  silent  mode;  do  not  print  identical  lines. 

V  Turn  off  silent  mode. 

e  1  Call  the  ed(l)  with  the  left  column. 

e  r  Call  ed(l)  with  the  right  column. 

e  b  Call  ed(  1)  with  the  concatenation  of  left  and  right  columns, 

e  Call  ed(l)  with  a  zero  length  file. 

On  exit  from  ed(l),  the  resulting  file  is  concatenated  to  the  named  output  file, 
q  Exit  from  the  program. 

EXAMPLES 

A  sample  output  of  sdiff  would  look  like  this: 

X  I  y 

a  a 

b  < 

c  < 

d  d 

>  c 
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SEE  ALSO 

diff(l),  ed(l) 
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NAME 

sed  -  stream  editor 
SYNOPSIS 

sed  [  -n  ]  [  -e  script  ]  [  -f  sfilename  ]  [filename  ]. . . 

SYSTEM  V  SYNOPSIS 

/usr/5bin/sed  [  -n  ]  [  -e  script  ]  [  -f  sfilename  ]  [filename  ]. . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.2  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

sed  copies  the  filenames  (standard  input  default)  to  the  standard  output,  edited  according  to  a  script  of  com¬ 
mands. 

OPTIONS 

-n  Suppress  the  default  output. 

-e  script  script  is  an  edit  command  for  sed.  If  there  is  just  one  -e  option  and  no  -f  options,  the 

-e  flag  may  be  omitted. 

-f  sfilename  Take  the  script  from  sfilename. 

USAGE 

sed  Scripts 

sed  scripts  consist  of  editing  commands,  one  per  line,  of  the  following  form: 

[  address  [,  address  ]  ^function  [  arguments  ] 

In  normal  operation  sed  cyclically  copies  a  line  of  input  into  a  pattern  space  (unless  there  is  something  left 
after  a  D  command),  sequentially  applies  all  commands  with  addresses  matching  that  pattern  space  until 
reaching  the  end  of  the  script,  copies  the  pattern  space  to  the  standard  output  (except  under  -n),  and  finally, 
deletes  the  pattern  space. 

Some  commands  use  a  hold  space  to  save  all  or  part  of  the  pattern  space  for  subsequent  retrieval. 

An  address  is  either: 

a  decimal  number  linecount,  which  is  cumulative  across  input  files; 
a  $,  which  addresses  the  last  input  line; 

or  a  context  address,  which  is  a  Iregular  expression!  in  the  style  of  ed(l); 
with  the  following  exceptions: 

\.^RE.?  In  a  context  address,  the  construction  \  ?regular  expression? ^  where  ?  is  any  character,  is 
identical  to  iregular  expression!.  Note:  in  the  context  address  \xabc\xdefx,  the  second  x 
stands  for  itself,  so  that  the  regular  expression  is  abcxdef. 

\n  Matches  a  NEWLINE  embedded  in  the  pattern  space. 

.  Matches  any  character  except  the  NEWLINE  ending  the  pattern  space. 

null  A  command  line  with  no  address  selects  every  pattern  space. 

address  Selects  each  pattern  space  that  matches. 
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address  1 ,  address2 

Selects  the  inclusive  range  from  the  first  pattern  space  matching  addrressl  to  the  first  pat¬ 
tern  space  matching  address2 .  Selects  only  one  line  if  addressl  is  greater  than  or  equal 
to  address2 . 

Comments 

If  the  first  nonwhite  character  in  a  line  is  a  *#*  (pound  sign),  sed  treats  that  line  as  a  comment,  and  ignores 
it  If,  however,  the  first  such  line  is  of  the  form: 

#n 

sed  runs  as  if  the  -n  flag  were  specified. 

Functions 

The  maximum  number  of  permissible  addresses  for  each  function  is  indicated  in  parentheses  in  the  list 
below. 

An  argument  denoted  text  consists  of  one  or  more  lines,  all  but  the  last  of  which  end  with  \  to  hide  the 
NEWLINE.  Backslashes  in  text  are  treated  like  backslashes  in  the  replacement  string  of  an  s  command,  and 
may  be  used  to  protect  initial  SPACE  and  TAB  characters  against  the  stripping  that  is  done  on  every  script 
line. 

An  argument  denoted  rfilename  or  wfilename  must  terminate  the  command  line  and  must  be  preceded  by 
exactly  one  SPACE.  Each  wfilename  is  created  before  processing  begins.  There  can  be  at  most  10  distinct 
wfilename  arguments. 

(1) a\ 

text  Append:  place  text  on  the  output  before  reading  the  next  input  line. 

(2)  b  label  Branch  to  the  * :  *  command  bearing  the  label .  Branch  to  the  end  of  the  script  if  label  is  emp¬ 

ty. 

(2)c\ 

text  Change:  delete  the  pattern  space.  With  0  or  1  address  or  at  the  end  of  a  2  address  range, 

place  text  on  the  output.  Start  the  next  cycle. 

(2)d  Delete  the  pattern  space.  Start  the  next  cycle. 

(2)  D  Delete  the  initial  segment  of  the  pattern  space  through  the  first  NEWLINE.  Start  the  next  cy¬ 

cle. 

(2)  g  Replace  the  contents  of  the  pattern  space  by  the  contents  of  the  hold  space. 

(2)  G  Append  the  contents  of  the  hold  space  to  the  pattern  space. 

(2)  h  Replace  the  contents  of  the  hold  space  by  the  contents  of  the  pattern  space. 

(2)  H  Append  the  contents  of  the  pattern  space  to  the  hold  space. 

(1) i\ 

text  Insert:  place  text  on  the  standard  output. 

(2)  I  List  the  pattern  space  on  the  standard  output  in  an  unambiguous  form.  Non-printing  charac¬ 

ters  are  spelled  in  two  digit  ASCH  and  long  lines  are  folded. 

(2)  n  Copy  the  pattern  space  to  the  standard  output.  Replace  the  pattern  space  with  the  next  line 

of  input. 

(2)N  Append  the  next  line  of  input  to  the  pattern  space  with  an  embedded  newline.  (The  current 

line  number  changes.) 

(2)  p  Print:  copy  the  pattern  space  to  the  standard  output. 
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(2)  P  Copy  the  initial  segment  of  the  pattern  space  through  the  first  NEWUNE  to  the  standard  out¬ 

put 

(1)  q  Quit:  branch  to  the  end  of  the  script.  Do  not  start  a  new  cycle. 

(2)  r  rfilename 

Read  the  contents  of  rfilename.  Place  them  on  the  output  before  reading  the  next  input  line. 
(2)  s/regular  expression! replacement! fiags 

Substitute  the  replacement  string  for  instances  of  the  regular  expression  in  the  pattern  space. 
Any  character  may  be  used  instead  of  7’.  For  a  fuller  description  see  ed(l).  flags  is  zero  or 
more  of; 

n  rt=  1  -  512.  Substitute  for  just  the  nth  occurrence  of  the  regularexpr&ssion. 

g  Global:  substitute  for  all  nonoverlapping  instances  of  the  regular  expression 

rather  than  just  the  first  one. 

p  Print  the  pattern  space  if  a  replacement  was  made. 

w  wfilename  Write:  append  the  pattern  space  to  wfilename  if  a  replacement  was  made. 

(2)  t  label  Test:  branch  to  the  command  bearing  the  label  if  any  substitutions  have  been  made  since 
the  most  recent  reading  of  an  input  line  or  execution  of  a  t.  If  label  is  empty,  branch  to  the 
end  of  the  script. 

(2)  w  wfilename 

Write:  append  the  pattern  space  to  wfilename. 

(2)  X  Exchange  the  contents  of  the  pattern  and  hold  spaces. 

(2)  yistringli  string!  i 

Transform:  replace  all  occurrences  of  characters  in  stringl  with  the  corresponding  character 
in  string! .  The  lengths  of  stringl  and  string!  must  be  equal. 

{2)1  function  Do  not:  apply  iht  function  (or  group,  if  function  is  *{’)  only  to  lines  not  selected  by  the 
address(es). 

(0) :  label  This  command  does  nothing;  it  bears  a  label  for  b  and  t  commands  to  branch  to.  Note:  the 
maximum  length  label  is  seven  characters. 

(1)  =  Place  the  current  line  number  on  the  standard  output  as  a  line. 

(2) {  Execute  the  following  commands  through  a  matching  *}’  only  when  the  pattern  space  is 

selected.  Commands  are  separated  by 

(0)  An  empty  command  is  ignored. 

System  V  sed  Scripts 

Initial  SPACE  and  TAB  characters  are  not  stripped  from  text  lines. 

DIAGNOSTICS 

Too  many  commands 

The  command  list  contained  more  than  200  commands. 

Too  much  command  text 

The  command  list  was  too  big  for  sed  to  handle.  Text  in  the  a,  c,  and  i  commands,  text  read  in  by 
r  commands,  addresses,  regular  expressions  and  replacement  strings  in  s  commands,  and  transla¬ 
tion  tables  in  y  commands  all  require  sed  to  store  data  internally. 

Command  line  too  long 

A  command  line  was  longer  than  4000  characters. 
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Too  many  line  numbers 

More  than  256  decimal  number  linecounts  were  specified  as  addresses  in  the  command  list. 

Too  many  files  in  w  commands 

More  than  10  different  files  were  specified  in  w  commands  or  w  options  for  s  commands  in  the 
command  list. 

Too  many  labels 

More  than  50  labels  were  specified  in  the  command  list. 

Unrecognized  command 

A  command  was  not  one  of  the  ones  recognized  by  sed. 

Extra  text  at  end  of  command 

A  command  had  extra  text  after  the  end. 

Illegal  line  number 

An  address  was  neither  a  decimal  number  linecount,  a  $,  nor  a  context  address. 

Space  missing  before  filename 

There  was  no  space  between  a  r  or  w  command,  or  the  w  option  for  a  s  command,  and  the 
filename  specified  for  that  command. 

Too  many  {’s 

There  were  more  {  than  }  in  the  list  of  commands  to  be  executed. 

Too  many  }’s 

There  were  more }  than  { in  the  list  of  commands  to  be  executed. 

No  addresses  allowed 

A  command  that  takes  no  addresses  had  an  address  specified. 

Only  one  address  allowed 

A  command  that  takes  one  address  had  two  addresses  specified. 

“\digit’*  out  of  range 

The  number  in  a  \n  item  in  a  regular  expression  or  a  replacement  string  in  a  s  command  was 
greater  than  9. 

Bad  number 

One  of  the  endpoints  in  a  range  item  in  a  regular  expression  (that  is,  an  item  of  the  form  {n}  or 
{n,m])  was  not  a  number. 

Range  endpoint  too  large 

One  of  the  endpoints  in  a  range  item  in  a  regular  expression  was  greater  than  255. 

More  than  2  numbers  given  in  \{  \} 

More  than  two  endpoints  were  given  in  a  range  expression, 

}  expected  after  \ 

A  \  appeared  in  a  range  expression  and  was  not  followed  by  a }. 

First  number  exceeds  second  in  \{  \} 

The  first  endpoint  in  a  range  expression  was  greater  than  the  second. 

Illegal  or  missing  delimiter 

The  delimiter  at  the  end  of  a  regular  expression  was  absent. 

\(  \)  imbalance 

There  were  more  \(  than  \),  or  more  \)  than  \(,  in  a  regular  expression. 
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[  ]  imbalance 

There  were  more  [  than  ],  or  more  ]  than  [,  in  a  regular  expression. 

First  RE  may  not  be  null 

The  first  regular  expression  in  an  address  or  in  a  s  command  was  null  (empty). 

Ending  delimiter  missing  on  substitution 

The  ending  delimiter  in  a  s  command  was  absent. 

Ending  delimiter  missing  on  string 

The  ending  delimiter  in  a  y  command  was  absent. 

Transform  strings  not  the  same  size 

The  two  strings  in  a  y  command  were  not  the  same  size. 

Suffix  too  large  -  512  max 

The  suffix  in  a  s  command,  specifying  which  occurrence  of  the  regular  expression  should  be  re¬ 
placed,  was  greater  than  512. 

Label  too  long 

A  label  in  a  command  was  longer  than  8  characters. 

Duplicate  labels 

The  same  label  was  specified  by  more  than  one :  command. 

File  name  too  long 

The  filename  specified  in  a  r  or  w  command,  or  in  the  w  option  for  a  s  command,  was  longer  than 
1024  characters. 

Output  line  too  long. 

An  output  line  was  longer  than  4000  characters  long. 

Too  many  appends  or  reads  after  line  n 

More  than  20  a  or  r  commands  were  to  be  executed  for  line  n. 

Hold  space  overflowed. 

More  than  4000  characters  were  to  be  stored  in  the  hold  space. 

SEE  ALSO 

awk(l),  ed(l),  grep(lV),  lex(l) 

Editing  Text  Files 

BUGS 

There  is  a  combined  limit  of  200  -e  and  -f  arguments.  In  addition,  there  are  various  internal  size  limits 
which,  in  rare  cases,  may  overflow.  To  overcome  these  limitations,  either  combine  or  break  out  scripts,  or 
use  a  pipeline  of  sed  commands. 
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NAME 

selection_svc  -  SunView  selection  service 

SYNOPSIS 

selection_svc  [  -d  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

The  SunView  selection  service  handles  the  state  and  rank  of  various  selections  for  its  client  programs.  A 
selection  service  is  started  automatically  by  sunview(l).  However,  you  can  also  start  one  explicitly  using 
the  se]ection_svc  command. 

OPTIONS 

-d  Debug  a  client  program.  Use  the  alternate  socket  provided  for  testing  and  debugging  a  client  pro¬ 
gram.  The  second  selection  service  invoked  with  the  -d  handles  a  different  set  of  selections,  and 
can  co-exist  with  one  started  in  the  normal  fashion.  Each  service  responds  only  to  requests  direct¬ 
ed  to  its  own  socket.  The  client  to  be  debugged  can  be  directed  to  use  the  “debugging”  service 
by  using  the  seln_usejest_service()  procedure,  as  described  in  the  SunView  System 
Programmer’s  Guide. 

SEE  ALSO 

sunview(l) 

SunView  User’s  Guide 

SunView  System  Programmer’ s  Guide 
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NAME 

set_alarm,  get_.alann»  ring_alaim  —  SunView  programmable  alarms 
SYNOPSIS 

set_alarm  [  -b  number  ]  [  -f  number  ]  [  -d  duration  ] 

get_alarni 

ring_alarm 

AVAILABILITY 

This  command  is  available  with  the  SunView  User's  software  installation  option.  Refer  to  Installing  SunOS 
4.1  for  more  information  on  how  to  install  optional  software. 

DESCRIPTION 

set_alarni  sets  the  WINDOW  ALARM  environment  variable  according  to  the  options  specified. 
get_alarm  returns  the  setting  of  WINDOW  ALARM  in  the  form: 

WINDOW_ALARM=jemVi^ 

ring_alarm  performs  the  actual  beeping  and  flashing  of  the  alarm.  Note:  the  (x:currence  of  the  alarm  is 
controlled  by  the  SunView/Visible_Bell  and  SunView/AudibIe_B€ll  settings  in  defaultsedit(l).  If  either 
of  these  is  disabled,  the  respective  feature  of  the  alarm  will  not  occur,  regardless  of  how  it  is  specified  by 
WINDOWALARM. 

In  the  C  shell,  set_alarni  echoes  the  following  command  to  set  the  WINDOW  ALARM  environment  vari¬ 
able: 

set  noglob, 'setenv  WlNDOW_ALARM  ^em>ig;unset  noglob; 

In  the  Bourne  shell,  set_alarin  echos  the  following: 

export  WINDOW_ALARM;WINDO  W_ALARM=5C/rmg ; 

Consequently,  set_alarm  is  should  be  used  as  follows: 
eval  ‘set_alarm  [optionsV 

OPTIONS 

-b  number  Specify  the  number  of  beeps.  The  default  is  1. 

-f  number  Specify  the  number  of  flashes.  The  default  is  1. 

-d  duration  Specify  the  duration  of  the  beep  in  milliseconds.  The  default  is  1000. 

ENVIRONMENT 

The  SunView  programmable  alarms  use  the  WINDOW_ALARM  environment  variable  to  define  the  charac¬ 
teristics  of  the  alarm.  The  variable  is  set  with  a  string  argument  of  the  following  form: 

:beeps=b:flashes=/:dur=/: 

SEE  ALSO 

csh(l),  defaultsedit(l),  sh(l) 

SunView  User’s  Guide 
DIAGNOSTICS 

get_alarm:  the  WINDOW_ALARM  environment  variable  is  NULL. 

This  message  is  self-explanatory. 

ring_alarm;  WINDOW  ALARM  is  NULL;  using  default  values. 

set_alarm  was  not  used  to  set  values  for  the  WINDOW„ALARM  environment  variable.  See 
OPTIONS  for  default  values. 

ring  alarm:  WINDOW  ME  not  found 

Attempted  to  ring  the  alarm  when  SunView  is  not  running. 
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BUGS  and  LIMITATIONS 


The  user  must  be  running  Sun  View  in  order  to  ring  the  alarm;  consequently,  the  alarms  cannot  be  used 
with  Open  Windows, 
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NAME 

sh  —  shell,  the  standard  UNIX  system  command  interpreter  and  command-level  language 
SYNOPSIS 

sh  [  -acefhiknstuvx  ]  [  arguments  ] 

DESCRIPTION 

sh,  the  Bourne  shell,  is  the  standard  UNIX-system  command  interpreter.  It  executes  commands  read  from  a 
terminal  or  a  file. 

Definitions 

A  blank  is  a  TAB  or  a  SPACE  character.  A  name  is  a  sequence  of  letters,  digits,  or  underscores  beginning 
with  a  letter  or  underscore.  A  parameter  is  a  name,  a  digit,  or  any  of  the  characters  *,  @,  #,  ?,  $,  and ! , 

Invocation 

If  the  shell  is  invoked  through  execve(2V),  exec( ),  see  execl(3V),  and  the  first  character  of  argument  zero 
is  commands  are  initially  read  from  /etc/profile  and  from  $HOME/.profile,  if  such  files  exist. 
Thereafter,  commands  are  read  as  described  below,  which  is  also  the  case  when  the  shell  is  invoked  as  sh. 

OPTIONS 

The  options  below  are  interpreted  by  the  shell  on  invocation  only;  unless  the  ~c  or  -s  option  is  specified, 
the  first  argument  is  assumed  to  be  the  name  of  a  file  containing  commands,  and  the  remaining  arguments 
are  passed  as  positional  parameters  for  use  with  the  commands  that  file  contains. 

“i  If  the  ~i  option  is  present  or  if  the  shell  input  and  output  are  attached  to  a  terminal,  this 

shell  is  interactive.  In  this  case  TERMINATE  is  ignored  (so  that  ‘kill  0’  does  not  kill  an 
interactive  shell)  and  INTERRUPT  is  caught  and  ignored  (so  that  wait  is  interruptible). 
In  all  cases,  QUIT  is  ignored  by  the  shell. 

-s  If  the  -s  option  is  present  or  if  no  arguments  remain  commands  are  read  from  the  stan¬ 

dard  input.  Any  remaining  arguments  specify  the  positional  parameters.  Shell  output 
(except  for  Special  Commands)  is  written  to  file  descriptor  2. 

-c  string  If  the  -c  option  is  present  commands  are  read  from  string. 

The  remaining  options  and  arguments  are  described  under  the  set  command,  under  Special  Commands, 
below, 

USAGE 

Refer  to  SunOS  User's  Guide:  Doing  More  for  more  information  about  using  the  shell  as  a  programming 
language. 

Commands 

A  simple  command  is  a  sequence  of  nonblank  words  separated  by  blanks.  The  first  word  specifies  the 
name  of  the  command  to  be  executed.  Except  as  specified  below,  the  remaining  words  are  passed  as  argu¬ 
ments  to  the  invoked  command.  The  command  name  is  passed  as  argument  0  (see  execve(2V)).  The  value 
of  a  simple  command  is  its  exit  status  if  it  terminates  normally,  or  (octal)  200+status  if  it  terminates  abnor¬ 
mally  (see  sigvec(2)  for  a  list  of  status  values). 

A  pipeline  is  a  sequence  of  one  or  more  commands  separated  by  ‘j’  (or,  for  historical  compatibility,  by  ‘^’). 
The  standard  output  of  each  command  but  the  last  is  connected  by  a  pipe  (see  pipe(2V))  to  the  standard 
input  of  the  next  command.  Each  command  is  run  as  a  separate  process;  the  shell  normally  waits  for  the 
last  command  to  terminate  before  prompting  for  or  accepting  the  next  input  line.  The  exit  status  of  a  pipe¬ 
line  is  the  exit  status  of  its  last  command. 
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A  list  is  a  sequence  of  one  or  more  simple  commands  or  pipelines,  separated  by  *&&’,  or  ‘I  I*  and 

optionally  terminated  by  or  *&’.  Of  these  four  symbols,  and  *&’  have  equal  precedence,  which  is 
lower  than  that  of  *&&’  and  *|  |’.  The  symbols  ‘&&’  and  ‘|  |’  also  have  equal  precedence.  A  semicolon  (;) 
sequentially  executes  the  preceding  pipeline;  an  ampersand  (&)  asynchronously  executes  the  preceding 
pipeline  (the  shell  does  not  wait  for  that  pipeline  to  finish).  The  symbols  &&  and  1 1  are  used  to  indicate 
condmonal  execution  of  the  list  that  follows.  With  &&  ,  list  is  executed  only  if  the  preceding  pipeline  (or 
command)  returns  a  zero  exit  status.  With  1 1,  list  is  executed  only  if  the  preceding  pipeline  (or  command) 
returns  a  nonzero  exit  status.  An  arbitrary  number  of  NEWLINE  characters  may  appear  in  a  list,  instead  of 
semicolons,  to  delimit  commands. 

A  command  is  either  a  simple  command  or  one  of  the  following  constructions.  Unless  otherwise  stated,  the 
value  returned  by  a  command  is  that  of  the  last  simple  command  executed  in  the  construction. 

for  name  [  in  word ...  ]  do  list  done 

Each  time  a  for  command  is  executed,  name  is  set  to  the  next  word  taken  from  the  in  word  list.  If 
in  word ...  is  omitted,  then  the  for  command  executes  the  do  list  once  for  each  positional  param¬ 
eter  that  is  set  (see  Parameter  Substitution  below).  Execution  ends  when  there  are  no  more 
words  in  the  list. 

case  word  in  [pattern[  | pattern  ] list esac 

A  case  command  executes  the  list  associated  with  the  first  pattern  that  matches  word.  The  form 
of  the  patterns  is  the  same  as  that  used  for  filename  generation  (see  Filename  Generation)  except 
that  a  slash,  a  leading  dot,  or  a  dot  immediately  following  a  slash  need  not  be  matched  explicitly. 

if  list  then  list  [  elif  list  then  list  ] . . .  [  else  list  ]  fi 

The  list  following  if  is  executed  and,  if  it  returns  a  zero  exit  status,  the  list  foUowing  the  first  then 
is  executed.  Otherwise,  the  list  following  elif  is  executed  and,  if  its  value  is  zero,  the  list  follow¬ 
ing  the  next  then  is  executed.  Failing  that,  the  else  list  is  executed.  If  no  else  list  or  then  list  is 
executed,  then  the  if  command  returns  a  zero  exit  status. 

while  list  do  list  done 

A  while  command  repeatedly  executes  the  while  list  and,  if  the  exit  status  of  the  last  command  in 
the  list  is  zero,  executes  the  do  list;  otherwise  the  loop  terminates.  If  no  commands  in  the  do  list 
are  executed,  then  the  while  command  returns  a  zero  exit  status;  until  may  be  used  in  place  of 
while  to  negate  the  loop  termination  test. 

( list )  Execute  list  in  a  subshell. 

{ list ;}  list  is  simply  executed. 

name  ()  {list;) 

Define  a  function  which  is  referenced  by  name.  The  body  of  the  function  is  the  list  of  commands 
between  {  and  }.  Execution  of  functions  is  described  below  (see  Execution). 

The  following  words  are  only  recognized  as  the  first  word  of  a  command  and  when  not  quoted: 

if  then  else  elif  fi  case  esac  for  while  until  do  done  {  } 

Comments 

A  word  beginning  with  #  and  all  the  following  characters  up  to  a  NEWLINE  are  ignored. 

Command  Substitution 

The  shell  reads  commands  from  the  string  between  two  grave  accents  (“)  and  the  standard  output  from 
these  commands  may  be  used  as  all  or  part  of  a  word.  Trailing  NEWLINE  characters  from  the  standard  out¬ 
put  are  removed. 

No  interpretation  is  done  on  the  string  before  the  string  is  read,  except  to  remove  backslashes  (\)  used  to 
escape  other  characters.  Backslashes  may  be  used  to  escape  a  grave  accent  (‘)  or  another  backslash  (\) 
and  are  removed  h^fore  the  command  string  is  read.  Escaping  grave  accents  allows  nested  command  sub¬ 
stitution.  If  the  command  substitution  lies  within  a  pair  of  double  quotes  a  backslash 

used  to  escape  a  double  quote  (\")  will  be  removed;  otherwise,  it  will  be  left  intact. 
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If  a  backslash  is  used  to  escape  a  NEWLINE  character  (\NEWLINE),  both  the  backslash  and  the  NEWLINE 
are  removed  (see  Quoting,  later).  In  addition,  backslashes  used  to  escape  dollar  signs  (\$)  are  removed. 
Since  no  interpretation  is  done  on  the  command  string  before  it  is  read,  inserting  a  backslash  to  escape  a 
dollar  sign  has  no  effect.  Backslashes  that  precede  characters  other  than  \,  ",  NEWLINE,  and  $  are  left 

intact  when  the  command  string  is  read. 

Parameter  Substitution 

The  character  $  is  used  to  introduce  substitutable  parameters.  There  are  two  types  of  parameters,  posi¬ 
tional  and  keyword.  If  parameter  is  a  digit,  it  is  a  positional  parameter.  Positional  parameters  may  be 
assigned  values  by  set.  Keyword  parameters  (also  known  as  variables)  may  be  assigned  values  by  writing: 

name=value  [  name=value  ] ... 

Pattern-matching  is  not  performed  on  value.  There  cannot  be  a  function  and  a  variable  with  the  same 
name. 

%i  parameter  } 

The  value,  if  any,  of  the  parameter  is  substituted.  The  braces  are  required  only  when  parameter  is 
followed  by  a  letter,  digit,  or  underscore  that  is  not  to  be  interpreted  as  part  of  its  name.  If  param¬ 
eter  is  ‘+’  or  all  the  positional  parameters,  starting  with  $1,  are  substituted  (separated  by 
SPACE  characters).  Parameter  $0  is  set  from  argument  zero  when  the  shell  is  invoked. 

If  the  colon  (:)  is  omitted  from  the  following  expressions,  the  shell  only  checks  whether  parameter  is  set  or 
not. 

%{parameter \—word) 

If  parameter  is  set  and  is  nonnull,  substitute  its  value;  otherwise  substitute  word. 

%{parameter  :=word} 

If  parameter  is  not  set  or  is  null  set  it  to  word\  the  value  of  the  parameter  is  substituted.  Positional 
parameters  may  not  be  assigned  to  in  this  way. 

Siparameter  ilword} 

If  parameter  is  set  and  is  nonnull,  substitute  its  value;  otherwise,  print  word  and  exit  from  the 
shell.  If  word  is  omitted,  the  message  'parameter  null  or  not  set*  is  printed. 

%{parame  teri^h  word) 

If  parameter  is  set  and  is  nonnull,  substitute  word;  otherwise  substitute  nothing. 

In  the  above,  word  is  not  evaluated  unless  it  is  to  be  used  as  the  substituted  string,  so  that,  in  the  following 
example,  pwd  is  executed  only  if  d  is  not  set  or  is  null: 

echo  ${c^:-‘pwd‘} 

The  following  parameters  are  automatically  set  by  the  shell: 

#  The  number  of  positional  parameters  in  decimal. 

-  Hags  supplied  to  the  shell  on  invocation  or  by  the  set  command. 

?  The  decimal  value  returned  by  the  last  synchronously  executed  command. 

$  The  process  number  of  this  shell. 

!  The  process  number  of  the  last  background  command  invoked. 

The  following  parameters  are  used  by  the  shell: 

HOME  The  default  argument  (home  directory)  for  the  cd  command. 

PATH  The  search  path  for  commands  (see  Execution  below). 

CDPATH  The  search  path  for  the  cd  command. 

MAIL  If  this  parameter  is  set  to  the  name  of  a  mail  file  and  the  MAILPATH  parameter 

is  not  set,  the  shell  informs  the  user  of  the  arrival  of  mail  in  the  specified  file. 
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MAILCHECK 


MAILPATH 


PSl 

PS2 

IFS 

SHELL 


This  parameter  specifies  how  often  (in  seconds)  the  shell  will  check  for  the 
arrival  of  mail  in  the  files  specified  by  the  MAILPATH  or  MAIL  parameters. 
The  default  value  is  600  seconds  (10  minutes).  If  set  to  0,  the  shell  will  check 
before  each  primary  prompt. 

A  colon  (:)  separated  list  of  filenames.  If  this  parameter  is  set,  the  shell  informs 
the  user  of  the  arrival  of  mail  in  any  of  the  specified  files.  Each  filename  can  be 
followed  by  %  and  a  message  that  will  be  printed  when  the  modification  time 
changes.  The  default  message  is  ‘you  have  mail’. 

Primary  prompt  string,  by  default  ‘$ 

Secondary  prompt  string,  by  default 

Internal  field  separators,  normally  SPACE,  TAB,  and  NEWLINE. 

When  the  shell  is  invoked,  it  scans  the  environment  (see  Environment  below) 
for  this  name. 


The  shell  gives  default  values  to  PATH,  PSl,  PSl,  MAILCHECK  and  IFS.  HOME  and  MAIL  are  set  by 
login(l). 


Blank  Interpretation 

After  parameter  and  command  substitution,  the  results  of  substitution  are  scanned  for  internal  field  separa¬ 
tor  characters  (those  found  in  IFS)  and  split  into  distinct  arguments  where  such  characters  are  found. 
Explicit  null  arguments  (’*"  or  ”)  are  retained.  Implicit  null  arguments  (those  resulting  from  parameters 
that  have  no  values)  are  removed. 

Input/Output 

A  command’s  input  and  output  may  be  redirected  using  a  special  notation  interpreted  by  the  shell.  The  fol¬ 
lowing  may  ^pear  anywhere  in  a  simple  command  or  may  precede  or  follow  a  command  and  are  not 
passed  on  to  the  invoked  command.  Note:  parameter  and  command  substitution  occurs  before  word  or 
digit  is  used. 

<word  Use  file  word  as  standard  input  (file  descriptor  0). 

>word  Use  file  word  as  standard  output  (file  descriptor  1).  If  the  file  does  not  exist  it  is  created; 

otherwise,  it  is  truncated  to  zero  length. 

>  >word  Use  file  word  as  standard  output.  If  the  file  exists  output  is  appended  to  it  (by  first  seek¬ 

ing  to  the  EOF);  otherwise,  the  file  is  created. 

<  <[-]word  After  parameter  and  command  substitution  is  done  on  word,  the  shell  input  is  read  up  to 
the  first  line  that  literally  matches  the  resulting  word,  or  to  an  EOF.  If,  however,  is 
appended  to: 

•  leading  TAB  characters  are  stripped  from  word  before  the  shell  input  is  read 
(but  after  parameter  and  command  substitution  is  done  on  word), 

•  leading  TAB  characters  are  stripped  from  the  shell  input  as  it  is  read  and 
before  each  line  is  compared  with  word,  and 

•  shell  input  is  read  up  to  the  first  line  that  literally  matches  the  resulting 
word,  or  to  an  EOF. 

If  any  character  of  word  is  quoted,  (see  Quoting,  later),  no  additional  processing  is  done 
to  the  shell  input.  If  no  characters  of  word  are  quoted: 

•  parameter  and  command  substitution  occurs, 

•  (escaped)  \NEWLINE  is  ignored,  and 

•  ‘\’  must  be  used  to  quote  the  characters  ‘$’,  and  “  ’ . 
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The  resulting  document  becomes  the  standard  input 

<&digit  Use  the  file  associated  with  file  descriptor  digit  as  standard  input.  Similarly  for  the  standard  out¬ 
put  using  >&digit. 

<&-  The  standard  input  is  closed.  Similarly  for  the  standard  output  using  *>&-'. 

If  any  of  the  above  is  preceded  by  a  digit,  the  file  descriptor  which  will  be  associated  with  the  file  is  that 
specified  by  the  digit  (instead  of  the  default  0  or  1).  For  example: 

...  2>&1 

associates  file  descriptor  2  with  the  file  currently  associated  with  file  descriptor  1. 

The  order  in  which  redirections  are  specified  is  significant.  The  shell  evaluates  redirections  left-to-right. 
For  example: 

...  \>xxx2>&l 

first  associates  file  descriptor  1  with  file  xxx.  It  associates  file  descriptor  2  with  the  file  associated  with  file 
descriptor  1  (namely,  file  xxx).  If  the  order  of  redirections  were  reversed,  file  descriptor  2  would  be  associ¬ 
ated  with  the  terminal  (assuming  file  descriptor  1  had  been)  and  file  descriptor  1  would  be  associated  with 
file  xxx. 

Using  the  terminology  introduced  on  the  first  page,  under  Commands,  if  a  command  is  composed  of 
several  simple  commands,  redirection  will  be  evaluated  for  the  entire  command  before  it  is  evaluated  for 
each  simple  command.  That  is,  the  shell  evaluates  redirection  for  the  entire  list,  then  each  pipeline  within 
the  list,  then  each  command  within  each  pipeline,  then  each  list  within  each  command. 

If  a  command  is  followed  by  &  the  default  standard  input  for  the  command  is  the  empty  file  /dev/null. 
Otherwise,  the  environment  for  the  execution  of  a  command  contains  the  file  descriptors  of  the  invoking 
shell  as  modified  by  input/output  specifications. 

Filename  Generation 

Before  a  command  is  executed,  each  command  word  is  scanned  for  the  characters  *?*,  and  ‘[  \  If  one 
of  these  characters  appears  the  word  is  regarded  as  a  pattern.  The  word  is  replaced  with  alphabetically 
sorted  filenames  that  match  the  pattern.  If  no  filename  is  found  that  matches  the  pattern,  the  word  is  left 
unchanged.  The  character  at  the  start  of  a  filename  or  immediately  following  a  7’,  as  well  as  the  char¬ 
acter  7’  itself,  must  be  matched  explicitly. 

*  Matches  any  string,  including  the  null  string. 

?  Matches  any  single  character. 

[...]  Matches  any  one  of  the  enclosed  characters.  A  pair  of  characters  separated  by 

matches  any  character  lexically  between  the  pair,  inclusive.  If  the  first  character  follow¬ 
ing  the  opening  [  is  a !  any  character  not  enclosed  is  matched. 

Quoting 

The  following  characters  have  a  special  meaning  to  the  shell  and  cause  termination  of  a  word  unless 
quoted: 

;&()!"<>  NEWLINE  SPACE  TAB 

A  character  may  be  quoted  (made  to  stand  for  itself)  by  preceding  it  with  a  backslash  (\)  or  inserting  it 
between  a  pair  of  quote  marks  (”  or  "").  During  processing,  the  shell  may  quote  certain  characters  to 
prevent  them  from  taking  on  a  special  meaning.  Backslashes  used  to  quote  a  single  character  are  removed 
from  the  word  before  the  command  is  executed.  The  pair  \NEWLINE  is  removed  from  a  word  before  com¬ 
mand  and  parameter  substitution. 
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All  characters  enclosed  between  a  pair  of  single  quote  marks  (”),  except  a  single  quote,  are  quoted  by  the 
shell.  Backslash  has  no  special  meaning  inside  a  pair  of  single  quotes.  A  single  quote  may  be  quoted 
inside  a  pair  of  double  quote  marks  (for  example,  "  *”). 

Inside  a  pair  of  double  quote  marks  parameter  and  command  substitution  occurs  and  the  shell  quotes 
the  resulte  to  avoid  blank  interpretation  and  file  name  generation.  If  $♦  is  within  a  pair  of  double  quotes, 
±e  positional  parameters  are  substituted  and  quoted,  separated  by  quoted  spaces  ("$1  $2  however,’ 
if  $@  is  within  a  pair  of  double  quotes,  the  positional  parameters  are  substituted  and  quoted,  separated  by 
unquoted  spaces  ("$1"  "$2"  , . .  \  quotes  the  characters  and  $.  The  pair  \NEW1JNE  is  removed 

before  parameter  and  command  substitution.  If  a  backslash  precedes  characters  other  than  and 

NEWLINE,  then  the  backslash  itself  is  quoted  by  the  shell. 

Prompting 

When  used  interactively,  the  shell  prompts  with  the  value  of  PSl  before  reading  a  command.  If  at  any  dme 
a  RETURN  is  typed  and  further  input  is  needed  to  complete  a  command,  the  secondary  prompt  (the  value  of 
PS2)  is  issued. 

Environment 

The  environment  (see  environ(5V))  is  a  list  of  name-value  pairs  that  is  passed  to  an  executed  program  in 
the  same  way  as  a  normal  argument  list.  The  shell  interacts  with  the  environment  in  several  ways.  On 
invocation,  the  shell  scans  the  environment  and  creates  a  parameter  for  each  name  found,  giving  it  the 
corresponding  value.  If  the  user  modifies  the  value  of  any  of  these  parameters  or  creates  new  parameters, 
none  of  these  affects  the  environment  unless  the  export  command  is  used  to  bind  the  shell* s  parameter  to 
the  environment  (see  also  ‘set  -a’).  A  parameter  may  be  removed  from  the  environment  with  the  unset 
command.  The  environment  seen  by  any  executed  command  is  thus  composed  of  any  unmodified  name- 
value  pairs  originally  inherited  by  the  shell,  minus  any  pairs  removed  by  unset,  plus  any  modifications  or 
additions,  all  of  which  must  be  noted  in  export  commands. 

The  environment  for  any  simple  command  may  be  augmented  by  prefixing  it  with  one  or  more  assignments 
to  parameters.  Thus: 

TERM=450cmd 

and 

(export  TERM;  TERM=450; 
are  equivalent  (as  far  as  the  execution  of  cmd  is  concerned). 

If  the  -k  option  is  set,  all  keyword  arguments  are  placed  in  the  environment,  even  if  they  occur  after  the 
command  name.  The  following  first  prints  a=b  c  and  c: 

echo  a=b  c 
set  -k 
echo  a=b  c 

Signals 

The  INTERRUPT  and  QUIT  signals  for  an  invoked  command  are  ignored  if  the  command  is  followed  by  &; 
otherwise  signals  have  the  values  inherited  by  the  shell  from  its  parent  (but  see  also  the  trap  command 
below).  INTERRUPT  is  handled  asynchronously. 
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Execution 

Each  time  a  command  is  executed,  the  above  substitutions  are  carried  out.  If  the  command  name  matches 
one  of  the  Special  Commands  listed  below,  it  is  executed  in  the  shell  process.  If  the  command  name  does 
not  match  a  Special  Command,  but  matches  the  name  of  a  defined  function,  the  function  is  executed  in  the 
shell  process  (note  how  this  differs  from  the  execution  of  shell  procedures).  The  positional  parameters  $1, 
$2,  —  are  set  to  the  arguments  of  the  function.  If  the  command  name  matches  neither  a  Special  Com¬ 
mand  nor  the  name  of  a  defined  function,  a  new  process  is  created  and  an  attempt  is  made  to  execute  the 
command  using  execve(2V). 

The  shell  parameter  PATH  defines  the  search  path  for  the  directory  containing  the  command.  Alternative 
directory  nanes  are  separated  by  a  colon  (:).  The  default  path  is  :/usr/ucb:/bin;/usr/bin  (specifying 
/usr/ucb,  /bin,  and  /usr/bin,  in  addition  to  the  current  directory).  Directories  are  searched  in  order.  The 
current  directory  is  specified  by  a  null  path  name,  which  can  appear  immediately  after  the  equal  sign 
(PATH=: . . . ),  between  the  colon  delimiters  (...:;  . . . )  anywhere  else  in  the  path  list,  or  at  the  end  of  the 
path  list  (...:),  If  the  command  name  contains  a  /  the  search  path  is  not  used.  Otherwise,  each  directory  in 
the  path  is  searched  for  an  executable  file.  If  the  file  has  execute  permission  but  is  not  an  binary  executable 
(see  a.out(5)  for  details)  or  an  executable  script  (with  a  first  line  beginning  with  #!)  it  is  assumed  to  be  a 
file  containing  shell  commands,  and  a  subshell  is  spawned  to  read  it.  A  parenthesized  command  is  also 
executed  in  a  subshell. 

The  location  in  the  search  path  where  a  command  was  found  is  remembered  by  the  shell  (to  help  avoid 
unnecessary  execs  later).  If  the  command  was  found  in  a  relative  directory,  its  location  must  be  re¬ 
determined  whenever  the  current  directory  changes.  The  shell  forgets  all  remembered  locations  whenever 
the  PATH  variable  is  changed  or  the  ‘hash  -r’  command  is  executed  (see  below). 

Special  Commands 

Input/output  redirection  is  now  permitted  for  these  commands.  File  descriptor  1  is  the  default  output  loca¬ 
tion. 


.  filename 

break  [  n  ] 
continue  [  n  ] 

cd[  arg  ] 


No  effect;  the  command  does  nothing.  A  zero  exit  code  is  returned. 

Read  and  execute  commands  from  filename  and  return.  The  search  path  specified  by 
PATH  is  used  to  find  the  directory  containing  filename. 

Exit  from  the  enclosing  for  or  while  loop,  if  any.  If  n  is  specified  break  n  levels. 

Resume  the  next  iteration  of  the  enclosing  for  or  while  loop.  If  n  is  specified  resume  at 
the  n’th  enclosing  loop. 

Change  the  current  directory  to  argument.  The  shell  parameter  HOME  is  the  default 
argument.  The  shell  parameter  CDPATH  defines  the  search  path  for  the  directory  con¬ 
taining  argument.  Alternative  directory  names  are  separated  by  a  colon  (:).  The  default 
path  is  NULL  (specifying  the  current  directory).  Note:  the  current  directory  is  specified 
by  a  null  path  name,  which  can  appear  immediately  after  the  equal  sign  or  between  the 
colon  delimiters  anywhere  else  in  the  path  list.  If  argument  begins  with  a  /  the  search 
path  is  not  used.  Otherwise,  each  directory  in  the  path  is  searched  for  argument. 


echo  [  argument ...  ] 

Echo  arguments.  See  echo(lV)  for  usage  and  description. 


eval  [  argument . . .  ] 

The  arguments  are  read  as  input  to  the  shell  and  the  resulting  command(s)  executed. 


exec  [  argument . . .  ] 

The  command  specified  by  the  arguments  is  executed  in  place  of  this  shell  without  creat¬ 
ing  a  new  process.  Input/output  arguments  may  appear  and,  if  no  other  arguments  are 
given,  modify  the  shell’s  input/output. 
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exit  [  n  ]  Exit  a  shell  with  the  exit  status  specified  by  n.  If  n  is  omitted  the  exit  status  is  that  of  the 

last  command  executed  (an  EOF  will  also  cause  the  shell  to  exit.) 

export  [  name  ...  ] 

The  given  names  are  marked  for  automatic  export  to  the  environment  of  subsequently- 
executed  commands.  If  no  arguments  are  given,  variable  names  that  have  been  marked 
for  export  during  the  current  shell’s  execution  are  listed.  (Variable  names  exported  from 
a  parent  shell  are  listed  only  if  they  have  been  exported  again  during  the  current  shell’s 
execution.)  Function  names  are  not  exported. 

getopts  Use  in  shell  scripts  to  parse  positional  parameters  and  check  for  legal  options.  See 

getopts(l)  for  usage  and  description. 

hash  [  — r  ]  [  name  . . .  ] 

For  each  name,  the  location  in  the  search  path  of  the  command  specified  by  name  is 
determined  and  remembered  by  the  shell.  The  -r  option  causes  the  shell  to  forget  all 
remembered  locations.  If  no  arguments  are  given,  information  about  remembered  com¬ 
mands  is  presented,  hits  is  the  number  of  times  a  command  has  been  invoked  by  the 
shell  process,  cost  is  a  measure  of  the  work  required  to  locate  a  command  in  the  search 
path.  If  a  command  is  found  in  a  “relative”  directory  in  the  search  path,  after  changing 
to  that  directory,  the  stored  location  of  that  command  is  recalculated.  Commands  for 
which  this  will  be  done  are  indicated  by  an  asterisk  (*)  adjacent  to  the  hits  information. 
cost  will  be  incremented  when  the  recalculation  is  done. 

login  [  argument . . .  ] 

Equivalent  to  ‘exec  login  argument. . , See  login(l)  for  usage  and  description, 
newgrp  [  argument . . .  ] 

Equivalent  to  ‘exec  newgrp  argument. . . .’  See  newgrp(l)  for  usage  and  description. 
Pwd  Print  the  current  working  directory.  See  pwd(l)  for  usage  and  description, 

read  [  name  ...  ] 

One  line  is  read  from  the  standard  input  and,  using  the  internal  field  separator,  IFS  (nor¬ 
mally  a  SPACE  or  TAB  character),  to  delimit  word  boundaries,  the  first  word  is  assigned 
to  the  first  name,  the  second  word  to  the  second  name,  etc.,  with  leftover  words  assigned 
to  the  last  name.  Lines  can  be  continued  using  \NEWLINE.  Characters  other  than  NEW- 
UNE  can  be  quoted  by  preceding  them  with  a  backslash.  These  backslashes  are 
removed  before  words  are  assigned  to  names,  and  no  interpretation  is  done  on  the  char¬ 
acter  that  follows  the  backslash.  The  return  code  is  0  unless  an  EOF  is  encountered. 

readonly  [  name  . . .  ] 

The  given  names  are  marked  readonly  and  the  values  of  the  these  names  may  not  be 
changed  by  subsequent  assignment.  If  no  arguments  are  given,  a  list  of  all  readonly 
names  is  printed. 

return  [  n  ]  Exit  a  function  with  the  return  value  specified  by  n.  If  /z  is  omitted,  the  return  status  is 
that  of  the  last  command  executed. 
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set  [  -aefhkntuvx-  [  argument . . .  ]  ] 

-a  Mark  variables  which  are  modified  or  created  for  export. 

-e  Exit  immediately  if  a  command  exits  with  a  nonzero  exit  status. 

-f  Disable  filename  generation. 

-h  Locate  and  remember  function  commands  as  functions  are  defined  (function 
commands  are  normally  located  when  the  function  is  executed). 

-k  All  keyword  arguments  are  placed  in  the  environment  for  a  command,  not  just 
those  that  precede  the  command  name. 

-n  Read  commands  but  do  not  execute  them. 

-t  Exit  after  reading  and  executing  one  command. 

-u  Treat  unset  variables  as  an  error  when  substituting. 

-V  Print  shell  input  lines  as  they  are  read. 

-X  Print  commands  and  their  arguments  as  they  are  executed. 

—  Do  not  change  any  of  the  options;  useful  in  setting  $1  to 

Using  ‘+’  rather  than  turns  off  these  options.  These  options  can  also  be  used  upon 
invocation  of  the  shell.  The  current  set  of  options  may  be  found  in  *$-*.  The  remaining 
arguments  are  positional  parameters  and  are  assigned,  in  order,  to  $1,  $2,  and  so  on.  If 
no  arguments  are  given,  the  values  of  all  names  are  printed. 

shift  [  n  ]  The  positional  parameters  are  shifted  to  the  left,  from  position  /i+l  to  position  1,  and  so 

on.  Previous  values  for  $1  through  $n  are  discarded.  If  w  is  not  given,  it  is  assumed  to 
bel. 

test  Evaluate  conditional  expressions.  See  test(lV)  for  usage  and  description, 

times  Print  the  accumulated  user  and  system  times  for  processes  run  from  the  shell, 

trap  [  ar^  ]  [  n  ] . . . 

The  command  arg  is  to  be  read  and  executed  when  the  shell  receives  signal(s)  n.  (Note: 
arg  is  scanned  once  when  the  trap  is  set  and  once  when  the  trap  is  taken.)  Trap  com¬ 
mands  are  executed  in  order  of  signal  number.  Any  attempt  to  set  a  trap  on  a  signal  that 
was  ignored  on  entry  to  the  current  shell  is  ineffective.  If  arg  is  absent  all  trap(s)  n  are 
reset  to  their  original  values.  If  arg  is  the  null  string  this  signal  is  ignored  by  the  shell 
and  by  the  commands  it  invokes.  If  n  is  0  the  command  arg  is  executed  on  exit  from  the 
shell.  The  trap  command  with  no  arguments  prints  a  list  of  commands  associated  with 
each  signal  number. 

type  [  name  ...  ]  For  each  name,  indicate  how  it  would  be  interpreted  if  used  as  a  command  name, 
umask  [  ooo  ] 

The  user  file-creation  mode  mask  is  set  to  ooo  (see  csh(l)).  The  three  octal  digits  refer 
to  read/write/execute  permissions  for  owner,  group,  and  others,  respectively.  The  value 
of  each  specified  digit  is  subtracted  from  the  corresponding  “digit”  specified  by  the  sys¬ 
tem  for  the  creation  of  a  file.  For  example,  umask  022  removes  group  and  others  write 
permission  (files  normally  created  with  mode  111  become  mode  755;  files  created  with 
mode  666  become  mode  644).  The  current  value  of  the  mask  is  printed  if  ooo  is  omit¬ 
ted. 
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unset  [  name 

For  each  name,  remove  the  corresponding  variable  or  function.  The  variables  PATH 
PSl,  PS2,  MAILCHECK  and  IPS  cannot  be  unset. 

wait  [  n  ]  Wait  for  the  background  process  whose  process  ID  is  n  and  report  its  termination  status. 

If  n  is  omitted,  all  the  shell’s  currently  active  background  processes  are  waited  for  and 
the  return  code  will  be  zero. 

EXIT  STATUS 

Errors  detected  by  the  shell,  such  as  syntax  errors,  return  a  nonzero  exit  status.  If  the  shell  is  being  used 
noninteractively  execution  of  the  shell  tile  is  abandoned.  Otherwise,  the  sheU  returns  the  exit  status  of  the 
last  command  executed  (see  also  the  exit  command  above). 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_defauIt  control  the  character  classification 
throughout  all  command  line  parsing.  These  variables  are  checked  in  the  following  order:  LC  CTYPE, 
LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for  character 
classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current  valid  charac¬ 
ter  classification  rules  of  LC_^CTYPE.  When  none  of  the  values  is  valid,  the  shell  character  classification 
defaults  to  the  POSDC.  1  “C”  locale. 

FILES 

/etc/profile 

$HOME/.profile 

/tmp/sh* 

/dev/nuU 

/usr/lib/rsh 

SEE  ALSO 

cd(l),  csh(l),  echo(lV),  env(l),  getopts(l),  login(l),  newgrp(l),  pwd(l),  test(lV),  wait(l),  diip(2V), 
ex«cve(2V),  fork(2V),  pipe(2V),  sigvec(2),  wait(2V),  execl(3V),  a.out(5),  environ(5V).  locale(5) 

SunOS  User* s  Guide:  Doing  More 
WARNINGS 

Words  used  for  filenames  in  input/output  redirection  are  not  interpreted  for  filename  generation  (see  File 
Name  Generation,  above).  For  example,  ‘cat  filel  >  a*’  will  create  a  file  named  ‘a*’. 

Because  commands  in  pipelines  are  run  as  separate  processes,  variables  set  in  a  pipeline  have  no  effect  on 
the  parent  shell. 

If  you  get  the  error  message  ‘cannot  fork,  too  many  processes’,  try  using  the  wait(l)  command  to  clean 
up  your  background  processes.  If  this  does  not  help,  the  system  process  table  is  probably  full  or  you  have 
too  many  active  foreground  processes.  There  is  a  limit  to  the  number  of  process  IDs  associated  with  your 
login,  and  to  the  number  the  system  can  keep  track  of. 
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BUGS 

If  a  command  is  executed,  and  a  command  with  the  same  name  is  installed  in  a  directory  in  the  search  path 
before  the  directory  where  the  original  command  was  found,  the  shell  will  continue  to  exec  the  original 
command.  Use  the  bash  command  to  correct  this  situation. 

If  you  move  the  current  directory  or  one  above  it,  pwd  may  not  give  the  correct  response.  Use  the  cd  com¬ 
mand  with  a  full  path  name  to  correct  this  situation. 

Not  all  the  processes  of  a  3-  or  more-stage  pipeline  are  children  of  the  shell,  and  thus  cannot  be  waited  for. 

For  wait  /i,  if  n  is  not  an  active  process  ID,  all  the  shell’s  currently  active  background  processes  are  waited 
for  and  the  return  code  will  be  zero. 
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NAME 

shelltool  run  a  shell  (or  other  program)  in  a  SunView  terminal  window 
SYNOPSIS 

shelltool  [  -C  ]  [  -B  boldstyle  ]  [  -I  command  ]  [  generic-tool-arguments  ]  [  program  [  arguments  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

shelltool  is  a  standard  SunView  facility  for  shells  or  other  programs  that  may  use  a  standard  tty-based  in¬ 
terface. 


When  invoked,  shelltool  runs  a  program,  (usually  a  shell)  in  an  interactive  terminal  emulator  based  on  a  tty 
subwindow.  Keyboard  input  is  passed  to  that  program.  If  the  program  is  a  shell,  it  accepts  commands  and 
runs  programs  in  the  usual  way. 

cmdtool(l),  which  provides  moused-based  editing,  logging,  and  scrolling  capabilities,  also  supports  shell- 
level  programs.  See  SunView  User’s  Guide  for  more  information. 


To  run  graphics  programs,  use  gfxtool(l). 


OPTIONS 

“C  Redirect  system  console  output  to  this  shelltool. 

-B  boldstyle  Set  the  style  for  displaying  bold  text  to  boldstyle.  boldstyle  can  be  a  string  specifying 
one  of  the  choices  for  the  /Tty/BoId__style  default,  see  Defaults  Options,  below,  or  it 
may  be  a  numerical  value  for  one  of  those  choices,  from  0  to  8,  corresponding  to  the 
placement  of  the  choice  in  the  list. 

-I  command  Pass  command  to  the  shell.  SPACE  characters  within  the  command  must  be  escaped. 
generic-tool-arguments 

shelltool  accepts  the  generic  tool  arguments  listed  in  sunview(l). 

If  a  program  argument  is  present,  shelltool  runs  it.  If  no  program  is  given,  shelltool  runs  the  program  indi¬ 
cated  by  the  SHELL  environment  variable,  or/usr/bin/sh  by  default. 


USAGE 

Defaults  Options 

These  options  are  available  through  defaultsedit(l). 
/Tty/Bold_style 

Select  a  style  for  emphasized  text: 


None 

Offset^X 

Offset_Y 

Offset_^X_and_Y 

Offset^XY 

Offset__X_and_XY 

Offset_Y_and  XY 

Offset^X_and_Y_and 

Invert 


Disable  emphasis. 

Thicken  characters  horizontally. 

Thicken  characters  vertically. 

Thicken  characters  both  horizontally  and  vertically. 
Thicken  characters  diagonally. 

Thicken  character  both  horizontally  and  diagonally. 
Thicken  characters  both  vertically  and  diagonally. 

XY 

Thicken  characters  horizontally,  vertically  and  diagonally. 
Display  emphasis  as  inverse  video  (the  standard  default). 


/Tty/Inverse_niode 

Select  a  style  for  inverse  video  display: 
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Enable  Enable  inverse  mode  for  inverted  text. 

Disable  Disable  inverse  mode  for  inverted  text 

Same_as__bold  Display  inverted  text  as  bold  text. 

/Tty/Underlme_mode 

Select  a  style  for  underlined  text: 

Enable  Enable  underline  mode  for  underlined  text. 

Disable  Disable  underline  mode  for  underlined  text, 

Saiiie_as_bold  Display  underlined  text  as  bold  text. 

/Tty/Retained 

When  set  to  “Yes”,  hidden  tty  subwindow  areas  are  retained  in  memory.  This  enhances  the  speed 
of  repainting  the  screen  at  the  expense  of  memory  area.  “No”  is  the  standard  default;  it  specifies 
that  tty  subwindows  are  not  retained. 


The  Terminal  Emulator 

The  tty  subwindow  is  a  terminal  emulator.  Whenever  a  tty  subwindow  is  created,  the  startup  file  V.ttyswrc 
is  read  for  initialization  parameters  that  are  specific  to  the  tty  subwindow. 

The  .ttyswrc  File 

A  sample  .ttyswrc  file  can  be  found  in  /usr/lib/ttyswrc.  The  command  format  for  this  file  is: 


# 

set  variable 
mapi  key  text 
mapo  key  text 


Comment, 

Turn  on  the  specified  variable. 

When  key  is  typed  pretend  text  was  input. 
When  key  is  typed  pretend  text  was  output. 


The  only  currently  defined  variable  is  pagemode,  key  is  one  of  L1-H5,  F1-F15,  T1-T15,  R1-R15,  LEFT, 
or  RIGHT  (see  note  below),  text  may  contain  escapes  such  as\E,  \n,  "X,  etc.  (ESC,  RETURN,  and  CTRL-X, 
respectively).  See  termcap(5)  for  the  format  of  the  string  escapes  that  are  recognized.  Note:  mapi  and 
mapo  may  be  replaced  by  another  keymapping  mechanism  in  the  future. 


When  using  the  default  kernel  keyboard  tables,  the  keys  LI,  LEFT,  RIGHT,  BREAK,  R8,  RIO,  R12,  and  R14 
cannot  be  mapped  in  this  way;  they  send  special  values  to  the  tty  subwindow.  Also,  when  using  the  default 
kernel  keyboard  tables,  Ll-LlO  are  now  used  by  Sun  View.  See  input Jrom_^defaults(l)  and  kbd(4S)  for 
more  information  on  how  to  change  the  behavior  of  the  keyboard. 

It  is  possible  to  have  terminal-based  programs  drive  the  tool  in  which  its  tty  subwindow  resides  by  sending 
special  escape  sequences.  These  escape  sequences  may  also  be  sent  by  typing  a  key  appropriately  mapped 
using  the  mapo  function  described  above.  The  following  functions  pertain  to  the  tool  in  which  the  tty 
subwindow  resides,  not  the  tty  subwindow  itself. 


\E[lt 

-open 

\E[2t 

-  close  (become  iconic) 

\E[3t 

-  move,  with  interactive  feedback 

\E[3;TOP;LEFTt 

-  move,  to  TOP  LEFT  (pixel  coordinates) 

\E[4t 

-  stretch,  with  interactive  feedback 

\E[4;HT;WIDTHt 

-  stretch,  to  HT  WIDTH  size  (in  pixels) 

\E[5t 

“  front 

\E[6t 

-back 

\E[7t 

-  refresh 

\E[8;ROWS;COLSt 

-  stretch,  to  ROWS  COLS  size  (in  characters) 

\E[llt 

-  report  if  open  or  iconic  by  sending  \E[lt  or  \E[2t 

\E[13t 

-  report  position  by  sending  \E[3;TOP;LEFTt 
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\E[14t  -  report  size  in  pixels  by  sending  \E[4;HT;WIDTHt 

-  report  size  in  characters  by  sending  \E[8;ROWS;COLSt 
\E[20t  -  report  icon  label  by  sending  \£]Llabel\E\ 

\EI21t  -  report  tool  header  by  sending  \£]Uabel\£\ 

\E]ltext\E\  -  set  tool  header  to  text 

\E]Ifile\E\  -  set  icon  to  the  icon  contained  in  file;  file  must  be  in  iconedit  output  for¬ 

mat 

\E]Llabel\E\  -  set  icon  label  to  label 

\E[>OPT; . .  .h  -  turn  SB  OPT  on  (OPT  =  1  =>  pagemode),  for  example,  \E[>l;3;4h 

\E[>OPT; . .  .k  -  report  OPT;  sends  \E[>OPTI  or  \E[>OPTh  for  each  OPT 

\E[>OPT; . .  .1  -  turn  OPT  off  (OPT  =  1  =>  pagemode),  for  example,  \E[>1;3;41 

See  EXAMPLES  for  an  example  of  using  this  facility. 

Selections 

Terminal  subwindows  support  a  selection  facility  that  allows  you  to  c^ture  a  block  of  text,  move  it 
between  windows,  and  replicate  it.  You  can  make  a  selection  by  clicking  the  left  button  on  the  mouse  at  the 
top-left  character  of  the  block  to  capture,  and  then  clicking  the  middle  button  on  the  bottom-right  character. 
The  selected  text  is  highlighted.  Multiple  clicks  of  the  LEFT  mouse  button  capture: 

1  click  a  character 

2  clicks  a  word 

3  clicks  a  line 

4  clicks  a  screenful 

You  can  also  make  a  selection  by  moving  the  mouse  while  holding  the  select  button,  and  then  releasing  it. 
The  selection  is  deselected  if  you  type  any  key  or  new  output  is  written  to  the  window  that  holds  the  selec¬ 
tion. 

Menu 

To  manipulate  your  selection,  press  the  menu  button  over  the  terminal  subwindow.  A  ttysw  menu  appears 
with  the  menu  items  discussed  below: 

Copy,  then  Paste  When  there  is  a  selection  in  any  window,  the  entire  item  is  active.  Selecting  it 
copies  the  selection  both  to  the  clipboard  and  to  the  insertion  point  (cursor).  It 
copies  selections  in  tty,  text,  command,  and  panel  subwindows,  and  It  is  intended 
to  bridge  the  gap  between  Stuff  and  the  selection  facility  (see  SunView  User’s 
Guide.  When  there  is  no  selection  but  there  is  text  on  the  clipboard,  only  Paste  is 
active.  In  this  case,  the  contents  of  the  clipboard  are  copied  to  the  insertion  point 
(cursor).  When  there  is  no  selection  and  nothing  on  the  clipboard,  this  item  is 
inactive. 

Toggle  page  mode  on  and  off.  Page  mode  prevents  output  from  scrolling  off  the 
screen.  It  is  an  alternative  to  more(l).  When  page  mode  is  on,  the  cursor  changes 
to  resemble  a  tiny  stop-sign  when  ever  a  screenful  of  output  is  displayed.  To  res¬ 
tart  output,  type  any  key,  or  select  the  Continue  menu  item  that  temporarily  re¬ 
places  Enable  Page  Mode. 

Stuff  is  provided  for  backward  compatibility.  It  copies  the  selectiott  sto  the  insertion 

point  (cursor)  as  though  they  had  been  typed  from  the  keyboard.  Stuff  can  only 
handle  selections  made  in  a  tty  subwindow. 


Enable  Page  Mode 
Disable  Page  Mode 
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Flush  Input 


EXAMPLES 


Occasionally  the  input  buffer  fills  up  and  the  terminal  emulator  appears  to  freeze. 
If  this  happens,  the  ‘Flush  Input’  aj^ars  in  the  menu;  choosing  it  clears  the 
buffer  and  allows  you  to  continue. 


The  following  aliases  can  be  put  into  your  7.cshrc  file: 


#  dynamically  set  the  name  stripe  of  the  tool: 
alias  header  ’echo-n  "\E]I\!*\E\'” 

#  dynamically  set  the  label  on  the  icon: 
alias  iheader  ’echo  -n  ''\E]L\I+\EV'’ 

#  dynamically  set  the  image  on  the  icon: 
alias  icon  ’echo-n  "\E]I\!+\EV'’ 

FILES 

“/.ttyswrc 

/usr/lib/ttyswrc 

/usr/demo/* 


SEE  ALSO 

cindtool(l),  defaultsedit(l),  gfxtool(l),  input_ft-oin_defauIts(I).  inore(l),  rlogin(lC),  sunview(l), 
kbd(4S),  termcap(5) 

SunView  User’s  Guide 

BUGS 

If  more  than  256  characters  are  input  to  a  terminal  emulator  subwindow  without  an  intervening  NEWLINE, 
the  terminal  emulator  may  hang.  If  this  occurs,  an  alert  will  come  up  with  a  message  saying  ‘Too  many 
keystrokes  in  input  buffer’.  Choosing  the  Flush  Input  Buffer  menu  item  may  correct  the  problem.  This 
is  a  bug  for  a  terminal  emulator  subwindow  running  on  top  of  or  rlogin(lC)  to  a  machine  with  pre-4.0 
release  kernel. 
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NAME 

size  -  display  the  size  of  an  object  61e 

SYNOPSIS 

size  [  object-file  . . .  ] 

Sun386i  SYNOPSIS 

/usr/bin/size  [-n]  [-f]  [-o]  [~x]  [-\]  filename . . . 

DESCRIPTION 

size  prints  the  (decimal)  number  of  bytes  required  by  the  text,  data,  and  bss  portions,  and  their  sum  in  hex 
and  decimal,  of  each  object-file  argument.  If  no  file  is  specified,  a.out  is  used. 

Sun386i  DESCRIPTION 

The  Sun386i  version  of  the  System  V  compatibility  package  includes  /usr/bin/size,  which  allows  the  Sys¬ 
tem  V  options  to  be  used,  and  creates  the  same  output  as  the  System  V  size(l)  command;  it  produces  sec¬ 
tion  size  information  in  bytes  for  each  loaded  section  in  COFF  files.  The  size  of  the  text,  data,  and  bss 
(uninitialized  data)  sections  is  printed,  as  well  as  the  sum  of  the  sizes  of  these  sections.  If  an  archive  file  is 
given,  it  displays  the  information  for  all  archive  members. 

Sun386i  OPTIONS 

-n  Includes  NOLOAD  sections  in  the  size. 

-f  Produces  full  output,  that  is,  it  prints  the  size  of  every  loaded  section,  followed  by  the  section 
name  in  parentheses. 

-0  Print  numbers  in  octal,  instead  of  the  default  which  is  decimal. 

-X  Print  numbers  in  hexadecimal. 

-V  Supply  version  information. 

Sun386i  DIAGNOSTICS 

size:  name:  cannot  open 

name  cannot  be  read, 

size:  name:  bad  magic 

name  is  not  an  appropriate  common  object  file. 

Suii386i  WARNINGS 

Since  the  size  of  bss  sections  is  not  known  until  link-edit  time,  this  command  does  not  give  the  true  total 
size  of  pre-linked  objects. 

SEE  ALSO 

cc(lV),  size(l),  a.out(5),  ar(5),  coff(5) 
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NAME 

sleep  -  suspend  execution  for  a  specified  interval 

SYNOPSIS 

sleep  time 

DESCRIPTION 

sleep  suspends  execution  for  time  seconds.  It  is  used  to  execute  a  command  after  a  certain  amount  of  time 
as  in: 

(sleep  105;  €ommand)& 

or  to  execute  a  command  every  so  often,  as  in: 

while  true 
do 

command 
sleep  37 

done 

SEE  ALSO 

sleep(3V) 

BUGS 

time  must  be  less  than  2,147,483,647  seconds. 
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NAME 

snap  -  SunView  application  for  system  and  network  administration 

SYNOPSIS 

snap 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

snap  simplifies  the  execution  of  a  variety  of  system  administration  tasks  in  the  user-friendly  environment 
of  a  SunView  window,  snap  eases  the  following  tasks:  personal  or  centralized  backup  and  restoration  of 
files,  management  of  users  accounts  and  user  groups,  software  installation,  network  administration,  and 
management  of  devices  such  as  printers,  terminals,  modems,  and  the  peripheral  box  containing  disk  and 
tape  drives. 

Anyone  can  use  snap,  but  the  operations  allowed  depend  on  the  secondary  group  membership  of  the  user  at 
the  time  that  snap  is  invoked.  There  are  four  secondary  user  groups  specifically  recognized  by  snap, 
membership  in  which  bestows  various  powers  over  the  corresponding  area  of  system  administration.  These 
are: 

accounts  users  and  user  groups. 

devices  printers,  terminals,  modems,  and  peripheral  box. 

operator  centralized  backup  and  restoration  of  files,  and  installation  of  software. 

networks  domains  and  systems,  including  the  New  User  Accounts  feature  and  Automatic  System  Instal¬ 
lation  features, 

A  user’s  snap  privileges  depend  upon  which  of  these  four  groups  he  or  she  belongs  to.  If  they  get  an  ac¬ 
count  through  New  User  Accounts,  or  if  an  administrator  adds  them  using  the  defaults,  new  users  become 
members  of  the  primary  group  users,  and  are  given  all  snap  privileges.  This  can  be  changed  by  changing 
the  secondary  group  membership  of  the  primary  group  users  with  snap.  Note:  this  does  not  change  the 
group  membership  of  existing  users,  but  only  of  new  users.  The  secondary  group  membership  of  existing 
users  must  be  changed  individually. 

Accounts 

An  administrator  using  snap  can  create  new  user  accounts  and  remove  existing  ones,  change  a  user’s  snap 
privileges,  and  control  users’  access  to  their  accounts.  New  users  can  create  their  own  accounts  as  they 
first  login  if  the  New  User  Accounts  feature  is  activated  as  described  under  Networks  below. 

Devices 

Epson  and  Epson-like  printers  (most  printers  using  the  Centronics  parallel  interface),  text  serial  printers, 
and  HP  LaserJet  and  compatible  printers  can  be  administered  with  snap .  The  supported  terminal  types  are 
vt-100  and  wyse.  The  supported  modem  types  are  Hayes  Smartmodem  or  a  modem  that  is  compatible  with 
Hayes  Smartmodem.  For  all  other  types  of  terminals,  modems,  or  printers,  the  software  must  be  configured 
manually.  See  System  and  Network  Administration  for  details, 

snap  can  add  or  remove,  display  and  change  information  about,  or  disable  or  enable  either  a  printer,  a  ter¬ 
minal,  a  modem,  or  the  peripheral  box  containing  disk  and  tape  drives.  Devices  not  added  using  snap  can 
not  be  manipulated  with  snap. 
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Operator 

Regardless  of  the  primary  or  secondary  group  membership  of  users,  they  can  backup  and  restore  their  own 
files  with  snap. 

Backup  and  removal  of  all  files  can  be  done  by  members  of  the  operator  group. 

Networks 

Much  of  the  network  setup  must  be  done  when  the  first  machine  in  the  network,  the  master  server,  is  start¬ 
ed  up,  and  when  each  client  is  connected  and  booted  for  the  first  time.  Some  of  this  information  can  never 
be  changed. 

Once  the  master  and  slave  servers  are  installed,  snap  can  be  used  to  add  and  assign  diskless  clients  to 
servers,  remove  them,  modify  their  network  roles,  and  perform  all  the  functions  listed  above  under  Ac¬ 
counts,  Devices,  and  Operator  on  any  system  in  the  network. 

If  desired,  you  can  also  enable  or  disable  the  feature  that  allows  a  user  to  create  his  own  account  while  log¬ 
ging  in  (New  User  Accounts),  and  the  automatic  system  installation  feature,  two  possible  security  loo¬ 
pholes. 

SEE  ALSO 

Sun386i  System  and  Network  Administration 
System  and  Network  Administration 
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NAME 

soelim  -  resolve  and  eliminate  .so  requests  from  nroff  or  troff  input 

SYNOPSIS 

soelim  [filename  . . .  ] 

AVAILABILITY 

This  command  is  available  wiUi  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.2  for  in¬ 
formation  on  how  to  install  optional  software. 

DESCRIPTION 

soelim  reads  the  specified  files  or  the  standard  input  and  performs  the  textual  inclusion  implied  by  the 
nroff  (1)  directives  of  the  form 

.so  somefile 

when  they  appear  at  the  beginning  of  input  lines.  This  is  useful  since  programs  such  as  tbl(l)  do  not  nor¬ 
mally  do  this;  it  allows  the  placement  of  individual  tables  in  separate  files  to  be  run  as  a  part  of  a  large  do¬ 
cument. 

An  argument  consisting  of  is  taken  to  be  a  file  name  corresponding  to  the  standard  input. 

Note:  inclusion  can  be  suppressed  by  using  ‘ ' '  instead  of  ‘ that  is, 

'  so  /usr/share/lib/tmac/tmac.s 

EXAMPLE 

A  sample  usage  of  soelim  would  be 
soelim  exum?.n  |  tbl  |  nroff 

SEE  ALSO 

colcrt(l),  more(l),  nroff(l),  tbl(l) 
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NAME 

sort  -  sort  and  collate  lines 
SYNOPSIS 

sort  [  -bdfiMnr  ]  [  -tc  ]  [  sort-field  . . .]  [  -emu  ]  [  -o[  ]output-file  ]  [  -T  directory  ] 

[  -y  kmem  ]  [  -z  recsz  ]  filename , . . 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/sort  [  -bdfiMnr  ]  [  -tc  ]  [  sort-field  . . .][  -emu  ]  [  -o[  ]output-file  ]  [  -T  directory  ] 

[  -y  kmem  ]  [  -z  recsz  ]  filename. . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

The  sort  program  sorts  and  collates  lines  contained  in  the  named  files,  and  writes  the  result  onto  the  stan¬ 
dard  output.  If  no  filename  argument  is  given,  or  if  appears  as  an  argument,  sort  accepts  input  from  the 
standard  input. 

Output  lines  are  normally  sorted  on  a  character-by-character  basis,  from  left  to  right  within  a  line.  The 
default  collating  sequence  is  the  ASCII  character  set.  Lines  can  also  be  sorted  according  to  the  contents  of 
one  or  more  fields  specified  by  a  sort-field,  specification,  using  the  +sw  (starting-word),  ~ew  (end-at-word), 
and  the  -tc  (set-TAB-character/word  delimiter)  options,  as  described  under  OPTIONS  below.  When  no 
word  delimiter  is  specified,  one  or  more  adjacent  white-space  characters  (SPACE  and  TAB)  signify  the  end 
of  the  previous  word;  the  lines: 

xyz 

xyz 

are  collated  as: 


Each  sort-field  is  evaluated  in  command-line  order;  later  fields  are  applied  to  the  sorting  sequence  only 
when  all  earlier  fields  compare  equally.  When  all  specified  fields  compare  equally  between  two  or  more 
lines,  that  subset  of  lines  is  sorted  on  a  character-by-character  basis,  from  left  to  right. 

SYSTEM  V  DESCRIPTION 

When  no  fields  are  specified  in  the  command  line,  the  System  V  version  of  sort  treats  leading  blanks  as 
significant,  even  with  the  ~n  (numeric  collating  sequence)  option;  the  lines: 

123 

23 

are  collated  as: 

23 

123 


OPTIONS 

Collating  Flags 

-b  Ignore  leading  SPACE  characters  when  determining  the  starting  and  ending  positions  of  a  field. 

-d  Dictionary  order.  Only  letters,  digits  and  the  white-space  characters  SPACE  and  TAB  are 

significant  in  comparisons. 

-f  Fold  in  lower  case.  Treat  upper-  and  lower-case  letters  equally  in  collating  comparisons, 

-i  Ignore  characters  outside  the  ASCn  range  040-0176  in  non-numeric  comparisons. 
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M  Month  order.  The  first  three  non-blank  characters  of  the  field  are  folded  to  upper  case  and  col¬ 
lated  according  to  the  sequence:  JAN  FEB  . . .  DEC.  Field  values  outside  this  range  appear  earlier 
than  JAN.  The  -M  option  implies  the  -b  option. 

-n  Numeric  collating  sequence.  An  initial  numeric  string,  consisting  of  optional  blanks,  optional 
minus  signs,  and  zero  or  more  digits  with  an  optional  decimal  point,  is  sorted  by  arithmetic  value. 
The  -n  option  implies  the  -b  option,  but  only  when  at  least  one  sort-field  is  specified  on  the  com¬ 
mand  line. 

~r  Reverse  the  current  collating  sequence. 

Field  Specificatioii  Options 

“tc  Use  c  as  the  word  delimiter  character;  unlike  white-space  characters,  adjacent  delimiters  indicate 
word  breaks;  if :  is  the  delimiter  character, ::  delimits  an  empty  word. 

sort-field 

This  is  a  combination  of  options  that  specifies  a  field,  within  each  line,  to  sort  on.  A  son-field 
specification  can  take  either  of  the  following  forms: 

+j>v[c/I 
+SW  -ewicf] 

where  sw  is  the  number  of  the  starting  word  (beginning  with  ‘0’)  to  include  in  the  field,  ew  is  the 
number  of  the  word  before  which  to  end  the  field,  and  cf  is  a  string  containing  collating  flags 
(without  a  leading  ‘-’.)  When  included  in  a  sort-field  specification,  these  flags  apply  only  to  the  field 
being  specified,  and  when  given,  override  other  collating  flags  given  in  separate  arguments  (which 
otherwise  apply  to  an  entire  line). 

If  the  -ew  option  is  omitted,  the  field  continues  to  the  end  of  a  line. 

You  can  apply  a  character  offset  to  jw  and  ew  to  indicate  that  a  field  is  to  start  or  end  a  given  number 
of  characters  within  a  word,  using  the  notation:  *w.c\  A  starting  position  specified  in  the  form: 
‘+w.c’  indicates  the  character  in  position  c  (beginning  with  0  for  the  first  character),  within  word  w 
(1  and  1.0  are  equivalent).  An  ending  position  specified  in  the  form:  ‘~w.c’  indicates  that  the  field 
ends  at  the  character  just  prior  to  position  c  (beginning  with  0  for  the  delimiter  just  prior  to  the  first 
character),  within  word  w.  If  the  -b  flag  is  in  effect,  c  is  counted  from  the  first  non-white-space  or 
non-delimiter  character  in  the  field,  otherwise,  delimiter  characters  are  counted. 

Other  Options 

— c  Check  that  the  input  file  is  sorted  according  to  the  ordering  rules;  give  no  output  unless  the  file  is 
out  of  sort, 

-m  Merge  only,  the  input  files  are  already  sorted. 

-u  Unique.  Emit  only  the  first  line  in  each  set  of  lines  for  which  all  sorting  fields  compare  equally. 

-ooutput-file 
-0  output-file 

Direct  output  to  the  file  specified  as  output-file,  instead  of  the  standard  output.  This  file  may  be 
the  same  as  one  of  the  input  files. 

-y  kmem 

The  amount  of  main  memory  used  by  the  sort  has  a  large  impact  on  its  performance.  Sorting  a 
small  file  in  a  large  amount  of  memory  is  a  waste.  If  this  option  is  omitted,  sort  begins  using  a 
system  default  memory  size,  and  continues  to  add  space  as  needed.  If  this  option  is  given  sort 
starts  with  kmem,  kilobytes  of  memory,  if  allowed,  or  as  close  to  that  amount  as  possible.  Supply¬ 
ing  -yO  guarantees  that  sort  starts  with  a  minimum  of  memory.  By  convention,  -y  (with  no  argu¬ 
ment)  starts  with  maximum  memory. 
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-z  recsz 

The  size  of  the  longest  line  read  is  recorded  in  the  sort  phase  so  that  buffers  can  be  allocated  dur¬ 
ing  the  merge  phase.  If  the  sort  phase  is  omitted  because  either  of  the  -c  or  -m  options  is  in 
effect,  a  default  size  of  1024  bytes  is  used.  Lines  longer  than  the  buffer  size  terminate  sort  abnor¬ 
mally.  Supplying  the  actual  number  of  bytes  in  the  longest  line  to  be  merged  (or  some  larger 
value)  avoids  this. 

~T  directory 

The  directory  argument  is  the  name  of  a  directory  in  which  to  place  temporary  files. 

EXAMPLES 

Sort  the  contents  of  input-file  with  word  number  1  (the  second  word)  as  the  sort  key: 
sort  +1  -2  input-file 

Sort,  in  reverse  order,  the  contents  of  input-filel  and  input-file2,  placing  the  output  in  output-file  and 
using  the  first  character  of  the  second  field  as  the  sort  key: 

sort  -r  -o  output-file  +1.0  -1.1  input-filel  input-file2 

Sort,  in  reverse  order,  the  contents  of  input-filel  and  input-file2  using  the  first  non-blank  character  of  the 
second  field  as  the  sort  key: 

sort  -r  +1.0b  -1.1b  input-filel  input-file2 

Print  the  password  file  (passwd(5))  sorted  by  the  numeric  user  ID  (the  third  colon-separated  field): 
sort  “t:  +2n  -3  /etc/passwd 

Print  the  lines  of  the  already  sorted  file  input-file,  suppressing  all  but  the  first  occurrence  of  lines  having 
the  same  third  field  (the  options  -mu  with  just  one  input  file  make  the  choice  of  a  unique  representative 
from  a  set  of  equal  lines  predictable): 

sort  -mu  +2  -3  input-file 

FILES 

/usr/tmp/stm??? 

SEE  ALSO 

comm(l),  join(l),  rev(l),  uniq(l) 

DIAGNOSTICS 

Comments  and  exits  with  non-zero  status  for  various  trouble  conditions  (such  as  when  input  lines  are  too 
long),  and  for  disorders  discovered  under  the  -c  option. 

When  the  last  line  of  an  input  file  is  missing  a  NEWLINE,  sort  appends  one,  prints  a  warning  message,  and 
continues. 
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NAME 

sortbib  -  sort  a  bibliographic  database 
SYNOPSIS 

sortbib  [  -sKEYS  ]  database. . . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  in¬ 
formation  on  how  to  install  optional  software. 

DESCRIPTION 

sortbib  sorts  files  of  records  containing  refer  key-letters  by  user-specified  keys.  Records  may  be  separated 
by  blank  lines,  or  by  *,[’  and  W  delimiters,  but  the  two  styles  may  not  be  mixed  together.  This  program 
reads  through  each  database  and  pulls  out  key  fields,  which  are  sorted  separately.  The  sorted  key  fields 
contain  the  file  pointer,  byte  offset,  and  length  of  corresponding  records.  These  records  are  delivered  using 
disk  seeks  and  reads,  so  sortbib  may  not  be  used  in  a  pipeline  to  read  standard  input. 

By  default,  sortbib  alphabetizes  by  the  first  %A  and  the  %D  fields,  which  contain  the  senior  author  and 
date.  The  -s  option  is  used  to  specify  new  KEYS.  For  instance,  -sATD  will  sort  by  author,  title,  and  date, 
while  -sA+D  will  sort  by  all  authors,  and  date.  Sort  keys  past  the  fourth  are  not  meaningful.  No  more 
than  16  databases  may  be  sorted  together  at  one  time.  Records  longer  than  4096  characters  will  be  truncat¬ 
ed. 

sortbib  sorts  on  the  last  word  on  the  %A  line,  which  is  assumed  to  be  the  author’s  last  name.  A  word  in 
the  final  position,  such  as  ‘jr.’  or  ‘ed.’,  will  be  ignored  if  the  name  beforehand  ends  with  a  comma.  Au¬ 
thors  with  two-word  last  names  or  unusual  constructions  can  be  sorted  correctly  by  using  the  nroff  conven¬ 
tion  ‘\0’  in  place  of  a  blank.  A  %Q  field  is  considered  to  be  the  same  as  %A,  except  sorting  begins  with 
the  first,  not  the  last,  word,  sortbib  sorts  on  the  last  word  of  the  %D  line,  usually  the  year.  It  also  ignores 
leading  articles  (like  ‘A’  or  ‘The’)  when  sorting  by  titles  in  the  %T  or  %J  fields;  it  will  ignore  articles  of 
any  modem  European  language.  If  a  sort-significant  field  is  absent  from  a  record,  sortbib  places  that 
record  before  other  records  containing  that  field. 

SEE  ALSO 

addbib(I),  indxbib(l),  lookbib(l),  refer(l),  roffbib(l) 
refer  in  Formatting  Documents 

BUGS 

Records  with  missing  author  fields  should  probably  be  sorted  by  title. 
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NAME 

spelK  hashmake,  spellin,  hashcheck  -  report  spelling  errors 
SYNOPSIS 

spell  [  “blvx  ]  [  ”d  hlisi  ]  [  -h  spellhist  ]  [  -s  hstop  ]  [  +  local Jile  ]  [filename  ] . . . 

/usr/lib/spell/hashmake 
/usr/lib/spell/spellin  n 
/usr/lib/spell/hashcheck  spellingjist 
DESCRIPTION 

spell  collects  words  from  the  named  files,  and  looks  them  up  in  a  hashed  spelling  list.  Words  that  do  not 
appear  in  the  list,  or  cannot  be  derived  from  those  that  do  appear  by  applying  certain  inflections,  prefixes  or 
suffixes,  are  displayed  on  the  standard  output. 

If  there  are  no  filename  arguments,  words  to  check  are  collected  from  the  standard  input,  spell  ignores 
most  troff(l),  tbl(l),  and  eqn(l)  constructs.  Copies  of  all  output  words  are  accumulated  in  the  history  file, 
and  a  stop  list  filters  out  misspellings  (for  example,  their=thy~y+ier)  that  would  otherwise  pass. 

By  default,  spell  (like  derofT(l))  follows  chains  of  included  files  (,so  and  .nx  troff(l)  requests),  unless  the 
names  of  such  included  files  begin  with  /usr/lib. 

If  a  +local  Jile  argument  is  specified,  words  found  in  local  Jile  are  removed  from  spell’s  output,  local Jile 
is  the  name  of  a  user-provided  file  that  contains  a  sorted  list  of  words,  one  per  line.  With  this  option,  the 
user  can  specify  a  set  of  words  that  are  correct  spellings  (in  addition  to  spell’s  own  spelling  list)  for  each 
job. 


The  standard  spelling  list  is  based  on  many  sources,  and  while  more  haphazard  than  an  ordinary  dictionary, 
is  also  more  effective  in  respect  to  proper  names  and  popular  technical  words.  Coverage  of  the  specialized 
vocabularies  of  biology,  medicine  and  chemistry  is  light. 


Three  programs  help  maintain  and  check  the  hash  lists  used  by  spell: 


hashmake  Reads  a  list  of  words  from  the  standard  input  and  writes  the  corresponding  nine-digit  hash 
code  on  the  standard  output. 


spellin  Reads  n  hash  codes  from  the  standard  input  and  writes  a  compressed  spelling  list  on  the 
standard  output. 

hashcheck  Reads  a  compressed  spellingjist  and  recreates  the  nine-digit  hash  codes  for  all  the  words  in 
it;  it  writes  these  codes  on  the  standard  output. 


OPTIONS 

“b  Check  British  spelling.  Besides  preferring  “centre”,  “colour”,  “programme”,  “speciality”, 

“travelled”,  and  so  on,  this  option  insists  upon  -ise  in  words  like  standardize,  despite  what 
Fowler  and  the  OED  say. 


-I  Follow  the  chains  of  all  included  files. 


-V 


Print  all  words  not  literally  in  the  spelling  list,  as  well  as  plausible  derivations  from  spelling 
list  words. 


~x  Print  every  plausible  stem  with  *=’  for  each  word. 

-d  hlist  Use  the  file  hlist  as  the  hashed  spelling  list. 

-h  spellhist  Place  misspelled  words  with  a  user/daie  stamp  in  file  spellhist. 
-s  hstop  Use  hstop  as  the  hashed  stop  list. 
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FILES 

/usr/Ub/spell/hlist[ab]  hashed  spelling  lists,  American  &  British 
/usr/Hb/spell/hstop  hashed  stop  list 
/usr/lib/spell/spellhist  history  file 

/usr/lib/spell/spellprog  program  called  by  the  /usr/bin/spell  shell  script 
SEE  ALSO 

deroff(l),  sed(lV),  sort(lV),  tee(l) 

BUGS 

The  spelling  list*s  coverage  is  uneven;  new  installations  may  wish  to  monitor  the  output  for  several  months 
to  gather  local  additions. 

British  spelling  was  done  by  an  American. 

NOTES 

Misspelled  words  can  be  monitored  by  default  by  setting  the  H_SPELL  variable  in  /usr/bin/spell  to  the 
name  of  a  file  that  has  permission  mode  666. 

spell  works  only  on  English  words  defined  in  the  US  ASCII  codeseL 
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NAME 

spline  -  interpolate  smooth  curve 

SYNOPSIS 

spline  [  -aknpx  ]  . . . 

DESCRIPTION 

spline  takes  pairs  of  numbers  from  the  standard  input  as  abcissas  and  ordinates  of  a  function.  It  produces  a 
similar  set,  which  is  approximately  equally  spaced  and  includes  the  input  set,  on  the  standard  output.  The 
cubic  spline  output  (R.  W.  Hamming,  Numerical  Methods  for  Scientists  and  Engineers,  2nd  ed.,  349ff)  has 
two  continuous  derivatives,  and  sufficiently  many  points  to  look  smooth  when  plotted,  for  example  by 
graph(lG). 

OPTIONS 

-a  Supply  abscissas  automatically  (they  are  missing  from  the  input);  spacing  is  given  by  the  next  argu¬ 
ment,  or  is  assumed  to  be  1  if  next  argument  is  not  a  number. 

— k  The  constant  k  used  in  the  boundary  value  computation 

y'd  =  W.  yn  = 

is  set  by  the  next  argument.  By  default  k  =  0. 

-n  Space  output  points  so  that  approximately  n  intervals  occur  between  the  lower  and  upper  x  limits. 
(Default  n  =  100.) 

-p  Make  output  periodic,  that  is,  match  derivatives  at  ends.  First  and  last  input  values  should  normally 
agree. 

-x  Next  1  (or  2)  arguments  are  lower  (and  upper)  x  limits.  Normally  these  limits  are  calculated  from  the 
data.  Automatic  abcissas  start  at  lower  limit  (default  0). 

SEE  ALSO 

graph(lG) 

R.  W.  Hamming,  Numerical  Methods  for  Scientists  and  Engineers,  2nd  ed. 

DIAGNOSTICS 

When  data  is  not  strictly  monotonic  in  x,  spline  reproduces  the  input  without  interpolating  extra  points. 

BUGS 

A  limit  of  1000  input  points  is  enforced  silently. 
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NAME 

split  -  split  a  file  into  pieces 
SYNOPSIS 

split  [  -number  ]  [  infile  [  outfile  ]  ] 

DESCRIPTION 

split  reads  infile  and  writes  it  in  number-VinQ  pieces  (default  1000)  onto  a  set  of  output  files  (as  many  files 
as  necessary).  The  name  of  the  first  output  file  is  outfile  with  aa  appended,  the  second  file  is  oufile  ab,  and 
so  on  lexicographically. 

If  no  outfile  is  given,  x  is  used  as  default  (output  files  will  be  called  xaa,  xab,  etc.). 

If  no  infile  is  given,  or  if  is  given  in  its  stead,  then  the  standard  input  file  is  used. 

OPTIONS 

-number 

Number  of  lines  in  each  piece. 
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NAME 

strings  -  find  printable  strings  in  an  object  file  or  binary 
SYNOPSIS 

strings  [  -  ]  [  -o  ]  [  -number  ]  filename  . . . 

DESCRIPTION 

strings  Imks  for  ASCII  strings  in  a  binary  file.  A  string  is  any  sequence  of  4  or  more  printing  characters 
ending  with  a  NEWLINE  or  a  null  character. 

strings  is  useful  for  identifying  random  object  files  and  many  other  things. 

OPTIONS 

Look  everywhere  in  the  file  for  strings.  If  this  flag  is  omitted,  strings  only  looks  in  the  initialized 
data  space  of  object  files. 

-o  Precede  each  string  by  its  offset  in  the  file. 

-number 

Use  number  as  the  minimum  string  length  rather  than  4. 

SEE  ALSO 

od(lV) 

NOTES 

strings  is  not  8-bit  clean  because  it  makes  too  many  mistakes  when  it  is  expected  to  look  for  strings  con¬ 
taining  non-ASCn  characters. 

BUGS 

The  algorithm  for  identifying  strings  is  extremely  primitive. 
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NAME 

Strip  -  remove  symbols  and  relocation  bits  from  an  object  file 

SYNOPSIS 

strip  filename . . . 

DESCRIPTION 

strip  removes  the  symbol  table  and  relocation  bits  ordinarily  attached  to  the  output  of  the  assembler  and 
linker.  This  is  useful  to  save  space  after  a  program  has  been  debugged. 

The  effect  of  strip  is  the  same  as  use  of  the  -s  option  of  ld(l). 

SEE  ALSO 

ld(l),  a.out(5) 

BUGS 

Unstripped  2.0  binary  files  will  not  run  if  stripped  by  the  3.0  version.  A  message  of  the  form: 

pid  XXX'.  killed  due  to  swap  problems  in  I/O  error  mapping  page, 
when  attempting  to  run  a  program  indicates  that  this  is  the  problem. 
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NAME 

stty  -  set  or  alter  the  options  for  a  terminal 
SYNOPSIS 

stty  [  -ag  ]  [  option  ] ... 

SYSTEM  V  SYNOPSIS 

/usr/5bin/stty  [  -ag  ]  [  option  ] . . . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

stty  sets  certain  terminal  I/O  options  for  the  device  that  is  the  current  standard  output.  Without  arguments, 
it  reports  the  settings  of  certain  terminal  options  for  the  device  that  is  the  standard  output;  the  settings  are 
reported  on  the  standard  error. 

Detailed  information  about  the  modes  listed  in  the  first  five  groups  below  may  be  found  in  termio(4).  Op¬ 
tions  in  the  last  group  are  implemented  using  options  in  the  previous  groups.  Note:  many  combinations  of 
options  make  no  sense,  but  no  sanity  checking  is  performed. 

SYSTEM  V  DESCRIPTION 

stty  sets  or  reports  terminal  options  for  the  device  that  is  the  current  standard  input;  the  settings  are  report¬ 
ed  on  the  standard  output. 


OPTIONS 

-a 

Special  Requests 
speed 

size 


Report  all  of  the  option  settings. 

Report  current  settings  in  a  form  that  can  be  used  as  an  argument  to  another  stty  command. 
The  terminal  speed  alone  is  printed  on  the  standard  output. 

The  terminal  (window)  sizes  are  printed  on  the  standard  output,  first  rows  and  then  columns. 

size  and  speed  always  report  on  the  settings  of  /dev/tty,  and  always  report  the  settings  to  the 
standard  output. 


Control  Modes 

Hparenb  Enable  parity  generation  and  detection.  With  a  disable  parity  checking. 

[— Jparodd  Select  odd  parity.  With  a  select  even  parity. 

cs5  cs6  cs7  cs8 

Select  character  size. 


0  Hang  up  phone  line  immediately. 

50  75 110  134  150  200  300  600  1200  1800  2400  4800  9600  19200  exta  38400  extb 

Set  terminal  baud  rate  to  the  number  given,  if  possible.  (Not  all  speeds  are  supported  by  all 
hardware  interfaces.) 

HhupcI  Hang  up  connection  on  last  close.  With  a  do  not  hang  up  connection. 

Hhup  Same  as  hupcl. 

Hcstopb  Use  two  stop  bits  per  character.  With  a  use  one  stop  bit  per  character. 

[~]cread  Enable  the  receiver.  With  a  disable  the  receiver. 

Hclocal  Assume  a  line  without  modem  control.  With  a  assume  a  line  with  modem  control. 
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Input  Modes 
[-Jignbrk 

Hbrkint 

Hignpar 

Hparmrk 

[-Jinpck 

Histrip 

Hinicr 

Higncr 

Hicrnl 

Hiuclc 

[~]ixon 

Hixany 

Hdecctlq 

Hixoff 

H  tandem 
Himaxbel 


Hiexten 


Output  Modes 
[-Jopost 

Holcuc 

Honicr 

[~]ocrnl 

Honocr 

[-Jonlret 

Hofill 
Hofdel 
crO  crl  cr2 

nlO  nil 


Ignore  break  on  input.  With  a  do  not  ignore  a  break  on  input. 

Signal  SIGINT  on  break.  With  a  do  not  signal. 

Ignore  parity  errors.  With  a  do  not  ignore  parity  errors. 

Mark  parity  errors  With  a  do  not  mark  parity  errors. 

Enable  input  parity  checking.  With  a  disable  input  parity  checking. 

Strip  input  characters  to  seven  bits.  With  a  do  not  strip  input  characters. 

Map  NEWLINE  to  RETURN  on  input.  With  a  do  not  map  on  input. 

Ignore  RETURN  on  input.  With  a  do  not  ignore  RETURN  on  input. 

Map  RETURN  to  NEWLINE  on  input.  With  a  do  not  map. 

Map  upper-case  alphabetics  to  lower  case  on  input.  With  a  do  not  map. 

Enable  START/STOP  output  control.  With  a  disable  output  control.  When  enabled, 
output  is  stopped  by  sending  a  STOP  character  and  started  by  sending  a  START  character. 

Allow  any  character  to  restart  output.  With  a  only  restart  with  a  START  character. 

Same  as  -ixany. 

Request  that  the  system  send  START/STOP  characters  when  the  input  queue  is  nearly 
empty/full.  With  a  request  that  the  system  not  send  START/STOP  characters. 

Same  as  ixoff. 

Request  that  the  system  send  a  BEL  character  to  your  terminal,  and  not  to  flush  the  input 
queue,  if  a  character  received  when  the  input  queue  is  full.  With  a  request  that  it  flush 
the  input  queue  and  not  send  a  BEL  character. 

Enable  all  SunOS  special  characters,  such  as  word  erase.  With  a  enable  only  the  POSIX 
subset  of  special  characters  (INTR,  QUIT,  ERASE,  KILL,  EOF,  NL,  EOL,  SUSP,  STOP, 
START,  and  CR). 

Post-process  output.  With  a  do  not  post-process  output;  ignore  all  other  output  modes. 
Map  lower-case  alphabetics  to  upper  case  on  output  With  a  do  not  map. 

Map  NEWLINE  to  RETURN-NEWLINE  on  output.  With  a  do  not  map. 

Map  RETURN  to  NEWLINE  on  output.  With  a  do  not  map. 

Do  not  place  RETURN  characters  at  column  zero.  With  a  do  place  RETURN  characters 
at  column  zero. 

On  the  terminal  NEWLINE  performs  the  RETURN  function.  With  a  NEWLINE  does  not 
perform  the  RETURN  function. 

Use  fill  characters  for  delays.  With  a  use  timing  for  delays. 

Fill  characters  are  DEL  characters.  With  a  fill  characters  are  NUL  characters. 
cr3 

Select  style  of  delay  for  RETURN  characters. 

Select  style  of  delay  for  LINEFEED  characters. 
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tabO  tabl tab2  tab3 


bsO  bsl 
ffOffl 
vtO  vtl 

Local  Modes 
Hisig 

Hicanon 

[-]cbreak 

[-]xcase 

Hecho 

Hechoe 

Hcrterase 

Hechok 

Iflcc 

Hechonl 

Hnoflsh 

Htostop 

Hechoctl 

[-Jctlecho 

Hechoprt 

Hprterase 

Hechoke 

Hcrtkill 


Select  style  of  delay  for  horizontal  TAB  characters. 
Select  style  of  delay  for  BACKSPACE  characters. 
Select  style  of  delay  for  form  FORMFEED  characters. 
Select  style  of  delay  for  vertical  TAB  characters. 


Enable  the  checking  of  characters  against  the  special  characters  INTR  and  QUIT.  With  a 
disable  this  checking. 

Enable  canonical  input  (ERASE,  KILL,  WERASE,  and  RPRNT  processing).  With  a  disable 
canonical  input. 

Same  as  -icanon. 

Perform  canonical  upper/lower-case  presentation.  With  a  do  not  perform  canonical 
upper/lower-case  presentation. 

Echo  back  every  character  typed.  With  a  do  not  echo  back. 

Echo  the  ERASE  character  as  a  sequence  of  BACKSPACE-SPACE-BACKSPACE.  With  a 
echo  the  ERASE  character  as  itself. 

Same  as  echoe. 

Echo  NEWLINE  after  echoing  a  KILL  character.  With  a  do  not  echo  NEWLINE  after 
echoing  a  KILL  character. 

Same  as  echok;  obsolete. 

Echo  NEWLINE,  even  if  echo  is  not  set.  With  a  do  not  echo  NEWLINE  if  echo  is  not 
set. 

Disable  flush  after  INTR  or  QUIT.  With  a  enable  flush. 

Stop  background  jobs  that  attempt  to  write  to  the  terminal.  With  a  allow  background 
jobs  to  write  to  the  terminal. 

Echo  control  characters  as  x  (and  delete  as  *?’.)  Print  two  BACKSPACE  characters  follow¬ 
ing  the  EOF  character  (default  CTRL-D).  With  a  echo  control  characters  as  themselves. 

Same  as  echoctl. 

Echo  erased  characters  backwards  within  ‘\’  and  7’;  used  on  printing  terminals.  With  a 
echo  erased  characters  as  indicated  by  echoe. 

Same  as  echoprt. 

Echo  the  KILL  character  by  erasing  each  character  on  the  line  as  indicated  by  echoprt  and 
echoe.  With  a  echo  the  KILL  character  as  indicated  by  echoctl  and  echok. 

Same  as  echoke. 


control-character  c 

Set  control-character  to  c,  where  control-character  is  one  of  erase,  kill,  intr,  quit,  eof,  eol, 
eoI2,  start,  stop,  susp,  rprnt,  flush,  werase,  or  Inext.  If  c  is  preceded  by  a  caret  ("j,  (es¬ 
caped  from  the  shell)  then  the  value  used  is  the  corresponding  CTRL  character  (for  instance, 
‘*D’  is  a  CTRL-D);  is  interpreted  as  DEL  and  is  interpreted  as  undefined. 

min  i  Set  the  MIN  value  to  i. 


530 


Last  change:  2  October  1989 


Sun  Release  4.1 


STTY(IV) 


USER  COMMANDS 


srrY(iv) 


time/  Set  the  TIME  value  to  i. 

rows  n  Set  the  recorded  number  of  rows  on  the  terminal  to  i. 

columns  i  Set  the  recorded  number  of  columns  on  the  terminal  to  i. 

cols  i  An  alias  for  columns  i. 

Combination  Modes 

cooked  Process  the  ERASE,  WERASE,  KILL,  INTR,  QUIT,  EOF,  EOL,  EOL2,  STOP,  START, 
SUSP,  RPRNT,  FLUSH,  and  LNEXT  characters  specially,  and  perform  output  post¬ 
processing. 

evenp  or  parity 

Enable  parenb,  disable  parodd,  and  set  cs7. 

oddp  Enable  parenb  and  parodd,  and  set  cs7. 

-evenp  or  -parity 

Disable  parenb,  and  set  cs8. 

-oddp  Disable  parenb  and  parodd,  and  set  cs8. 

pass8  Disable  parenb  and  istrip,  and  set  cs8. 

-passS  Enable  parenb  and  istrip,  and  set  cs7. 

litout  Disable  parenb,  istrip,  and  opost,  and  set  cs8. 

“litout  Enable  parenb,  istrip,  and  opost,  and  set  cs7. 

[-]raw  Enable  raw  input  and  output.  With  a  disable  raw  I/O.  In  raw  mode,  there  is  no  special 
processing  of  the  ERASE,  WERASE,  KILL,  INTR,  QUIT,  EOF,  EOL,  EOL2,  STOP,  START, 
SUSP,  RPRNT,  FLUSH,  nor  LNEXT  characters,  nor  is  there  any  other  input  pre-processing 
nor  output  post-processing,  brkint,  istrip,  imaxbel,  and  parenb  are  disabled,  and  cs8  is  set. 

[-]nl  Unset  icrnl,  onlcr.  With  a  set  them.  In  addition  -nl  unsets  inlcr,  igncr,  ocrnl,  and 

onlret. 

[-Jlcase  Set  xcase,  iucic,  and  olcuc.  With  a  unset  them. 

HLCASE  Same  as  lease  (-lease). 

[-]tabs 

tab3  Preserve  TAB  characters  when  printing.  With  a  or  with  tab3,  expand  TAB  characters  to 

SPACE  characters. 

ek  Reset  the  ERASE  and  KILL  characters  back  to  normal:  DEL  and  CTRL-U). 

sane  Reset  all  modes  to  some  reasonable  values. 

ert  Set  options  for  a  CRT  (echoe,  echoed,  and,  if  >=  1200  baud,  echoke.) 

dec  Set  all  modes  suitable  for  Digital  Equipment  Corp.  operating  systems  users  (ERASE,  KILL, 

and  INTR  characters  to "?,  “U,  and  *C,  deccUq,  and  crt.) 

term  Set  all  modes  suitable  for  the  terminal  type  term,  where  term  is  one  of  tty 33,  tty 37,  vt05, 

tn300,  ti700,  or  tek.  -ertsets  Raise  the  RTS  (Request  to  Send)  modem  control  line. 
Suspends  output  until  the  CTS  (Clear  to  Send)  line  is  raised. 
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ENVIRONMENT 

The  environment  variables  LC^CTYPE,  LANG,  and  LC__ciefault  control  the  character  classification 
throughout  stty.  On  entry  to  stty,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC  default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  "C”  locale. 

SEE  ALSO 

ioctl(2),  termio(4),  locaIe(5) 
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NAME 

stty_from_defaults  -  set  terminal  editing  characters  from  the  defaults  database 

SYNOPSIS 

stty_from_defaults 

AVAILABILITY 

This  command  is  available  with  the  SunView  Users  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  opdonal  software. 

DESCRIPTION 

stty_ft’om_defauUs  is  a  utility  provided  with  the  SunView  environment, 

stty_from_defaults  sets  the  three  editing  characters  (to  erase  a  character,  erase  a  word,  and  kill  a  line)  ac¬ 
cording  to  the  choices  in  your  defaults  database.  It  does  not  set  any  other  tty  options.  If  you  run  stty(lV) 
in  your  .login  or  rc.local  files,  you  may  want  to  run  stty_from_defaults  immediately  after  it.  This  will 
override  any  settings  of  sttyomst,  stiywQrase,  or  j//ykill,  so  that  you  will  have  the  same  character-editing 
behavior  with  SunView  application  programs. 

To  specify  the  editing  characters  stty  from  defaults  will  set,  run  defaultsedit(l)  and  select  the  "Text" 
category.  The  editing  characters  are  called  Edit_back_char,  Edit_back_word,  and  Edit_back_line.  Type 
the  value  you  want  to  the  right  of  each  item.  To  specify  CTRL-X,  type  ‘  X’ —  that  is,  the  three  characters 
‘V,  and  ‘X’.  To  specify  DEL,  type  ‘?’. 

If  you  do  not  specify  your  own  values,  the  default  values  are  DEL,  CTRL-W,  and  CTRL-U,  respectively. 
SEE  ALSO 

defaultsedit(l),  stty(lV),  sunview(l) 

SunView  User’s  Guide 
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NAME 

su  -  super-user,  temporarily  switch  to  a  new  user  ID 
SYNOPSIS 

su  [  - }  [  -f  ]  [  username  [  arg. . .  ]  ] 

SYSTEM  V  SYNOPSIS 

su  [  -  ]  [  username  [  arg. . .  ]  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installarion  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

su  creates  a  new  shell  process  that  has  the  user  ID  for  the  specified  username  as  its  real  and  effective  user 
ID.  su  asks  for  the  password,  just  as  if  you  were  logging  in  as  username^  and,  if  the  password  is  given, 
changes  the  real  and  effective  user  IDs  and  group  IDs  and  group  set  to  those  of  username  and  invokes  the 
shell  specified  in  the  password  file  for  that  username,  without  changing  the  cuirent  directory.  The  user  en¬ 
vironment  is  thus  unchanged  except  for  HOME  and  SHELL,  which  are  taken  from  the  password  file  for  the 
user  being  substituted  (see  environ(5V)).  If  username  is  not  root,  USER  is  changed  to  username.  The 
new  user  ID  stays  in  force  until  the  shell  exits. 

The  new  shell  will  not  be  a  login  shell,  so  it  will  not  read  username ’s  .login  or  .profile  files,  but  it  will  read 
any  other  configuration  files  for  that  user  (for  instance,  the  .cshrc  file  for  the  C  sheU)  just  as  if  that  user  had 
invoked  a  new  shell. 

If  no  username  is  specified,  root  is  assumed.  If  the  wheel  group  (group  0)  does  not  contain  a  null  user  list 
and  has  members,  only  they  can  su  to  root,  even  with  the  root  password.  To  remind  the  super-user  of  his 
responsibilities,  the  shell  substitutes  ‘#’  for  ’$’  or  in  its  usual  prompt  (except  if  you  will  be  running 
sh(l)  and  PSl  is  set  -  in  this  case,  the  prompt  will  not  be  modified).  If  args  are  given,  they  are  passed  to 
username's  shell. 

Any  additional  arguments  given  on  the  command  line  are  passed  to  the  program  invoked  as  the  shell. 
When  using  programs  like  sh(l)  and  csh(l),  an  arg  of  the  form  -c  string  executes  string  via  the  shell. 

OPTIONS 

-  Perform  a  complete  login.  Remove  all  variables  from  the  environment  except  for 

TERM,  set  USER  to  username,  set  HOME  and  SHELL  as  specified  above,  set  PATH  to 
;/usr/ucb:/bin:/usr/bin,  change  directories  to  username's  home  directory,  and  tell  the 
shell  to  read  username ’s  .login  or  .profile  file. 

Perform  a  fast  su  by  passing  the  -f  flag  to  the  shell.  This  flag  is  only  meant  for  use  with 
the  C  shell;  it  will  prevent  the  C  shell  from  reading  username  *s  .cshrc  file.  If  it  is  used 
with  the  Bourne  shell,  it  will  disable  filename  generation. 

FILES 

.cshrc 

.login 

.profile 

SEE  ALSO 

csh(l),  login(l),  sh(l),  environ(5V) 

NOTES 

SU  does  not  accept  8-bit  user  IDs.  See  login(l)  for  explanations  about  why  8-bit  login  names  are  not  accept¬ 
able. 
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BUGS 

su  fails  when  run  from  within  a  subdirectory  of  a  directory  that  username  either  cannot  search,  or  cannot 
read  (that  is,  username  does  not  have  both  read  and  execute  permission). 

su  fails  to  reset  the  user  ID  to  root  when  the  current  working  directory  is  in  an  NFS-mounted  file  system, 
and  does  not  have  its  search  permission  set  for  “other"  users. 
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NAME 

sum  ~  calculate  a  checksum  for  a  file 

SYNOPSIS 

sum  filename 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/sum  [  -r  ]  filename 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

sum  calculates  and  displays  a  16-bit  checksum  for  the  named  file,  and  also  displays  the  size  of  the  file  in 
kilobytes.  It  is  typically  used  to  look  for  bad  spots,  or  to  validate  a  file  communicated  over  some  transmis¬ 
sion  line.  The  checksum  is  calculated  by  an  algorithm  which  may  yield  different  results  on  machines  with 
16-bit  ints  and  machines  with  32-bit  ints,  so  it  cannot  always  be  used  to  validate  that  a  file  has  been 
transferred  between  machines  with  different-sized  ints. 

SYSTEM  V  DESCRIPTION 

sum  calculates  and  prints  a  16-bit  checksum  for  the  named  file,  and  also  prints  the  number  of  512-byte 
blocks  in  the  file.  It  is  typically  used  to  look  for  bad  spots,  or  to  validate  a  file  communicated  over  some 
transmission  line.  This  algorithm  is  independent  of  the  size  of  ints  on  the  machine. 

SYSTEM  V  OPTIONS 

The  option  -r  causes  the  (machine-dependent)  algorithm  used  by  the  non-System  V  sum  to  be  used  in 
computing  the  checksum. 

SEE  ALSO 

wc(l) 

DIAGNOSTICS 

Read  error  is  indistinguishable  from  EOF  on  most  devices;  check  the  block  count. 
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(  \  NAME 

sunview  -  the  SunView  window  environment 
SYNOPSIS 

sunview  [  -i  ]  [  -p  ]  [  -B I  -F I  -P  ]  [  -S  ]  [  -8bit_color_onIy  ]  [  “Overlay__only  ]  [  -toggle_enable  ] 

[  -b  red  green  blue  ]  [  -d  display-device  ]  [  -f  red  green  blue  ]  [  -k  keyboard-device  ] 

[  — m  mouse-device  ]  [  -~n  I  -s  startup-filename  ]  [  -background  raster-filename  ] 

[  -pattern  on  I  off  i  gray  I  iconedit-filename  ] 

DESCRIPTION 

sunview  starts  up  the  SunView  environment  and  (unless  you  have  specified  otherwise)  a  default  layout  of  a 
few  useful  “tools,”  or  window-based  applications. 

See  Start-up  Processing  below  to  learn  how  to  specify  your  own  initial  layout  of  tools.  Some  of  the 
behavior  of  sunview  is  controlled  by  settings  in  your  defaults  database;  see  SunView  Defaults  below,  and 
defaultsedit(l)  for  more  information. 

To  exit  sunview  use  the  Exit  SunView  menu  item.  In  an  emergency,  type  CTRUD  then  CTRL-Q  (there  is 
no  confirmation  in  this  case). 

Invert  the  background  and  foreground  colors  used  on  the  screen.  On  a  monochrome 
monitor,  this  option  provides  a  video  reversed  image.  On  a  color  monitor,  colors  that 
are  not  used  as  the  background  and  foreground  are  not  affected. 

Print  to  the  standard  output  the  name  of  the  window  device  used  for  the  sunview  back¬ 
ground. 

Use  the  “background  color”  ( -b )  for  the  background. 

Use  the  “foreground  color”  ( -f  )  for  the  background. 

Use  a  stipple  pattern  for  the  background.  This  option  is  assumed  unless  -F  or  -B  is 
specified. 

Set  Click-to-type  mode,  allowing  you  to  select  a  window  by  clicking  in  it.  Having  done 
so,  input  is  directed  to  that  window  regardless  of  the  position  of  the  pointer,  until  you 
click  to  select  some  other  window. 

-8bit_coIor_only 

For  multiple  plane  group  frame  buffers,  only  let  windows  be  created  in  the  8  bit  color 
plane  group.  This  frees  up  the  black  and  white  overlay  plane  to  have  a  separate  desktop 
running  on  it.  This  option  is  usually  used  with  the  “toggIe_enable  option.  See  Multiple 
Desktops  on  the  Same  Screen,  below. 

For  multiple  plane  group  frame  buffers,  only  let  windows  be  created  in  the  black  and 
white  overlay  plane  group.  This  frees  up  the  8  bit  color  plane  group  to  have  a  separate 
desktop  running  in  it.  This  option  is  usually  used  with  the  -toggle_enable  option.  See 
Multiple  Desktops  on  the  Same  Screen,  below. 

For  multiple  plane  group  frame  buffers,  when  sliding  the  pointer  between  different  desk¬ 
tops  running  within  different  plane  groups  on  the  same  screen,  change  the  enable  plane 
to  allow  viewing  of  the  destination  desktop.  See  Multiple  Desktops  on  the  Same 
Screen,  below. 


-overlay  _only 


-toggle_enable 
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~b  red  green  blue 

Specify  values  for  the  red,  green  and  blue  components  of  the  background  color.  If  this 
option  is  not  specified,  each  component  of  the  background  color  is  255  (white).  Sun 
3/1 10  system  users  that  use  this  option  should  use  the  — 8bit_color  only  option  as  well. 

-d  display-device  Use  display-device  as  the  output  device,  rather  than  /dev/fb  the  default  frame  buffer 
device, 

-f  red  green  blue  Specify  values  for  the  red,  green  and  blue  components  of  the  foreground  color.  If  this 
option  is  not  specified,  each  component  of  the  foreground  color  is  0  (black).  Sun  3/110 
system  users  that  use  this  option  should  use  the  -8bit_color_only  option  as  well. 

— k  keyboard-device 

Accept  keyboard  input  from  keyboard-device,  rather  than  /dev/kbd,  the  default  key¬ 
board  device, 

-m  mouse-device  Use  mouse-device  as  the  system  pointing  device  (locator),  rather  than  /dev/mouse,  the 
default  mouse  device. 

Bypass  startup  processing  by  ignoring  the  /usr/lib/.sunview  and  "/.sunview  (and  “/.sun- 
tools)  files. 

-s  startup-filename 

Read  startup  commands  from  startup-filename  instead  of  /usr/lib/.sunview  or  “/.sun- 
view). 

-background  raster-filename 

Use  the  indicated  raster  file  as  the  image  in  your  background.  The  raster  file  can  be 
created  with  screendump(l).  Screen  dumps  produced  on  color  monitors  currently  do 
not  work  as  input  to  this  option.  Small  images  are  centered  on  the  screen. 

-pattern  on  I  off  I  gray!  iconedit-filename 

Use  the  indicated  “pattern”  to  cover  the  background,  on  means  to  use  the  default  desk¬ 
top  gray  pattern,  off  means  to  not  use  the  default  desktop  gray  pattern,  gray  means  to 
use  a  50%  gray  color  on  color  monitors,  iconedit-filename  is  the  name  of  a  file  produced 
with  iconedit(l)  which  contains  an  image  that  is  to  be  replicated  over  the  background. 

USAGE 

Windows 

The  SunView  environment  always  has  one  window  open,  referred  to  as  the  background,  which  covers  the 
whole  screen.  A  solid  color  or  pattern  is  its  only  content  Each  application  is  given  its  own  window  which 
lies  on  top  of  some  of  the  background  (and  possibly  on  top  of  other  applications).  A  window  obscures  any 
part  of  another  window  which  lies  below  it. 

Input  to  Windows 

Mouse  input  is  always  directed  to  the  window  that  the  pointer  is  in  at  the  time.  Keyboard  input  can  follow 
mouse  input  or,  it  can  remain  within  a  designated  window  using  the  Click-to-Type  default  setting.  If  you 
are  not  using  Click-to-Type,  and  the  pointer  is  on  the  background,  keyboard  input  is  discarded.  Input  ac¬ 
tions  (mouse  motions,  button  clicks,  and  keystrokes)  are  synchronized,  which  means  that  you  can  “type- 
ahead”  and  “mouse-ahead,”  even  across  windows. 

Mouse  Buttons 

LEFT  mouse  button  Click  to  select  or  choose  objects. 

MIDDLE  mouse  button  In  text,  click  once  to  shorten  or  lengthen  your  selection.  In  graphic  apphcations  or 
on  the  desktop,  press  and  hold  to  move  objects. 
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RIGHT  mouse  button  Press  and  hold  down  to  invoke  menus. 

Menus 

sunview  provides  pop-up  menus.  There  are  two  styles  of  pop-up  menus:  an  early  style»  called  “stacking 
menus,”  and  a  newer  style,  called  “walking  menus”  (also  known  as  “pull-right  menus”).  In  the  current 
release,  walking  menus  are  the  default;  stacking  menus  are  still  available  as  a  defaults  option. 

Usually,  a  menu  is  invoked  by  pressing  and  holding  the  RIGHT  mouse  button.  The  menu  remains  on  the 
screen  as  long  as  you  hold  the  RIGHT  mouse  button  down.  To  choose  a  menu  item,  move  the  pointer  onto 
it  (it  is  then  highlighted),  then  release  the  RIGHT  mouse  button. 

Another  available  option  is  “stay-up  menus.”  A  stay-up  menu  is  invoked  by  pressing  and  releasing  the 
RIGHT  mouse  button.  The  menu  appears  on  the  screen  after  you  release  the  RIGHT  mouse  button.  To 
choose  a  menu  item,  move  the  pointer  onto  it  (it  is  then  highlighted),  then  press  and  release  the  RIGHT 
mouse  button  a  second  time.  Stay-up  menus  are  an  option  in  your  defaults  database;  see  SunView  De¬ 
faults  below. 

With  walking  menus,  any  menu  item  can  have  an  arrow  pointing  (=>)  to  the  right.  Moving  the  pointer  onto 
this  arrow  pops  up  a  “sub-menu,”  with  additional  items.  Choosing  the  item  with  an  arrow  (the  “pull-right 
item”)  invokes  the  first  item  on  the  sub-menu. 

The  SunView  Menu 

You  can  use  the  default  SunView  menu  to  start  SunView  applications  and  perform  some  useful  functions. 
To  invoke  it,  hold  down  the  RIGHT  mouse  button  when  the  pointer  is  anywhere  in  the  background. 

The  default  SunView  menu  is  defined  in  ihe  file  /usr/lib/.rootmenu.  It  consists  of  four  sub-menus,  labeled 
Shells,  Editors,  Tools,  and  Services,  along  with  an  Exit  SunView  item.  These  sub-menus  contain  the  fol¬ 
lowing  items: 

Shells 


Command  Tool  Bring  up  a  cmdtool(l),  a  scrollable  window-based  terminal  emulator 
that  supports  a  shell. 

Shell  Tool  Bring  up  a  shelltool(l),  an  tty-based  terminal  emulator  that  supports  a 
shell. 


Graphics  Tool  Bring  up  a  gfxtool(l),  for  running  graphics  programs. 

Console  Bring  up  a  Console  window,  a  cmdtool  with  the  -C  flag,  to  act  as  the 

system  console.  Since  many  system  messages  can  be  directed  to  the 
console,  there  should  always  be  a  console  window  on  the  screen. 

Editors 


Text  Editor 
Defaults  Editor 

Icon  Editor 
Font  Editor 


Bring  up  a  textedit(l),  for  reading  and  editing  text  files. 

Bring  up  a  defaultsedit(l),  for  browsing  or  changing  your  defaults 
settings. 

Bring  up  a  new  iconedit(l). 

Bring  up  a  fontedit(l). 


Tools 


Mail  Tool  Bring  up  a  mailtool(l),  for  reading  and  sending  mail. 
Dbx  (Debug)  Tool 

Bring  up  a  dbxtool(l),  a  window-based  source  debugger. 
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Performance  Meter 

Bring  up  a  perfmeter(l)  to  monitor  system  performance. 

Clock  Bring  up  a  new  clock(l). 

Services 

Redisplay  AH  Redraw  the  entire  screen.  Use  this  to  repair  damage  done  by 
processes  that  wrote  to  the  screen  without  consulting  the  Sun  View  sys¬ 
tem. 

Printing  There  are  two  items  on  this  submenu,  Check  Printer  Queue  and 

Print  Selected  Text.  Check  Printer  Queue  displays  the  printer 
queue  in  your  console;  Print  Selected  Text  sends  selected  text  to  the 
standard  printer. 

Remote  Login  There  are  two  items  on  this  submenu,  ‘Command  Tool’  and  ‘Shell 
Tool’.  Each  creates  a  terminal  emulator  that  prompts  for  a  machine 
name  and  then  starts  a  shell  on  that  machine. 

Save  Layout  Writes  out  a  "/.sunview  file  that  sun  view  can  then  use  when  starting 
up  again.  An  existing  7.sunview  file  is  saved  as  ~/.sunview-. 

Lock  Screen  Completely  covers  the  screen  with  a  graphics  display,  and  “locks”  the 
workstation  until  you  type  your  password.  When  you  “unlock”  the 
workstation,  the  screen  is  restored  as  it  was  when  you  locked  it.  See 
lockscreen(l)  for  details. 

Exit  Sun  View  Exit  from  sunview,  including  all  windows,  and  kill  processes  associat¬ 

ed  with  them.  You  return  to  the  shell  from  which  you  started  sunview. 

You  can  specify  your  own  Sun  View  menu;  see  SunView  Defaults  below  for  details. 

The  Frame  Menu 

A  small  set  of  universal  functions  are  available  through  the  Frame  menu.  There  are  also  accelerators  for 

some  of  these  functions,  described  under  Frame  Menu  Accelerators,  below. 

You  can  invoke  the  Frame  menu  when  the  cursor  is  over  a  part  of  the  application  that  does  not  provide  an 

application-specific  menu,  such  as  the  frame  header  (broad  stripe  holding  the  application’s  name),  the 

border  stripes  of  the  window,  and  the  icon. 

Close 

Open  Toggle  the  application  between  closed  (iconic)  and  open  state.  Icons  are  placed  on  the 

screen  according  to  the  icon  policy  in  your  defaults  database;  see  Sun  View  Defaults 

below.  When  a  window  is  closed,  its  underlying  processes  continue  to  run. 

Move  Moves  the  application  window  to  another  spot  on  the  screen.  Move  has  a  sub-menu 

with  two  items:  Unconstrained  and  Constrained. 

Unconstrained  Move  the  window  both  horizontally  and  vertically. 

Constrained  Moves  are  either  vertical  or  horizontal,  but  not  both. 

Choosing  Move  invokes  an  Unconstrained  move. 

Resize  Shrink  or  stretch  the  size  of  a  window  on  the  screen.  Resize  has  a  sub-menu  containing: 

Unconstrained  Resize  the  window  both  horizontally  and  vertically. 

Constrained  Resize  vertically  or  horizontally,  but  not  both. 

Choosing  Resize  invokes  an  Unconstrained  resize. 
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UnZoom 

Zoom  Zoom  expands  a  window  vertically  to  the  full  height  of  the  screen. 

UnZoom  undoes  this. 

FullScreen  Make  a  window  the  full  height  and  width  of  the  screen. 

Front  Bring  the  window  to  “the  top  of  the  pile.”  The  whole  window  becomes  visible,  and  hides 

any  window  it  happens  to  overlap  on  the  screen. 

Put  the  window  on  the  “bottom  of  the  pile”.  The  window  is  hidden  by  any  window 
which  overlaps  it. 

Props  Display  the  property  sheet.  (Only  active  for  applications  that  provide  a  property  sheet.) 

Redisplay  Redraw  the  contents  of  the  window. 

Quit  Notify  the  application  to  terminate  gracefully.  Requires  confirmation. 

Frame  Menu  Accelerators 

Accelerators  are  provided  for  some  Frame  menu  functions.  You  can  invoke  these  functions  by  pushing  a 
single  button  in  the  window’s  frame  header  or  outer  border.  See  the  Sun  View  Beginner’s  Guide  for  more 
details. 

Open  Click  the  LEFT  mouse  button  when  the  pointer  is  over  the  icon. 

Move  Press  and  hold  the  MIDDLE  mouse  button  while  the  pointer  is  in  the  frame  header  or 

outer  border.  A  bounding  box  that  tracks  the  mouse  is  displayed  while  you  hold  the 
button  down.  When  you  release  the  button,  the  window  is  redisplayed  within  the 
bounding  box.  If  the  pointer  is  near  a  comer,  the  move  is  Unconstrained.  If  it  is  in 
the  center  third  of  an  edge,  the  move  is  Constrained. 

Resize  Hold  the  CTRL  key  and  press  and  hold  the  MIDDLE  mouse  button  while  the  pointer 

is  in  the  frame  header  or  outer  border.  A  bounding  box  is  displayed,  and  one  side  or 
comer  tracks  the  mouse.  If  the  pointer  is  near  a  comer  when  you  press  the  mouse 
button,  the  resize  is  Unconstrained;  if  in  the  middle  third  of  an  edge,  the  resize  is 
Constrained. 

Zoom 

UnZoom  Hold  the  CTRL  key  and  click  the  LEFT  mouse  button  while  the  pointer  is  in  the  frame 

header  or  outer  border. 

Front  Click  the  LEFT  mouse  button  while  the  pointer  is  on  the  frame  header  or  outer  bord¬ 

er. 

Back  Hold  the  SHIFT  key  and  click  the  LEFT  mouse  button  while  the  pointer  is  on  the 

frame  header  or  outer  border. 

In  addition,  you  can  use  two  function  keys  as  even  faster  accelerators.  To  expose  a  window  that  is  partially 
hidden,  press  the  Front  function  key  (normally  L5)  while  the  pointer  is  anywhere  in  that  window.  Or,  if 
the  window  is  completely  exposed,  use  the  Front  key  to  hide  it.  Similarly,  to  close  an  open  window,  press 
the  Open  key  (normally  L7)  while  the  pointer  is  anywhere  in  that  window.  If  the  window  is  iconic,  use  the 
Open  key  to  open  it. 

In  applications  with  multiple  windows,  you  can  often  adjust  the  border  between  two  windows  up  or  down, 
without  changing  the  overall  size  of  the  application:  hold  the  CTRL  key,  press  the  MIDDLE  mouse  button 
over  the  boundary  between  the  two  windows,  and  adjust  the  size  of  the  (bounded)  subwindow  as  with 
Resize. 
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Startup  Processing:  The  .sunview  File 

Unless  you  override  it,  sunview  starts  up  with  a  predefined  layout  of  windows.  The  default  layout  is 
specified  in  the  file  /usr/lib/.sunview.  If  there  is  a  file  called  .sunview  in  your  home  directory,  it  is  used  in¬ 
stead.  For  compatibility  with  earlier  releases,  if  there  is  no  .sunview  file  in  your  home  directory,  but  a 
.suntools  file  instead,  the  latter  file  is  used. 


Sun  View  Defaults 

SunView  allows  you  to  customize  the  behavior  of  applications  and  packages  by  setting  options  in  a  de¬ 
faults  database  (one  for  each  user).  Use  defaultsedit(l)  to  browse  and  edit  your  defaults  database.  Select 
the  “SunView”  category  to  see  the  following  items  (and  some  others): 

Walking_menus  If  enabled,  the  Sun  View  menu,  the  Frame  menu,  and  many  applications  will  use 
walking  menus.  Applications  that  have  not  been  converted  will  still  use  stacking 
menus.  If  disabled,  applications  will  use  stacking  menus.  The  default  value  is  “En¬ 
abled.” 

Click_to_Type  If  enabled,  keyboard  input  will  stay  in  a  window  until  you  click  the  LEFT  or  MIDDLE 
mouse  button  in  another  window.  If  disabled,  keyboard  input  will  follow  the  mouse. 
The  default  value  is  “Disabled.” 


Font  You  can  change  the  SunView  default  font  by  giving  the  full  pathname  of  the  font 

you  want  to  use.  Some  alternate  fonts  are  in  the  directory 
/usr/lib/fonts/fixedwidthfonts.  The  default  font  from  the  SunOS  2.0  release  was 
/usr/lib/fonts/fixedwidthfonts/screen.r.l3.  The  default  value  is  null,  which  has  the 
same  effect  as  specifying  /usr/Iib/fonts/fixedwidthfonts/screen.r.ll. 

Rootmenu_filename  You  can  change  the  SunView  menu  by  giving  the  full  pathname  of  a  file  that 
specifies  your  own  menu.  See  The  SunView  Menu  File  below  for  details.  The  de¬ 
fault  value  is  null,  which  gives  you  the  menu  found  in  /usr/lib/.rootmenu. 

Icon_gravity  Determine  which  edge  of  the  screen  (“North”,  “South”,  “East”,  or  “West”)  icons  will 

place  themselves  against.  The  default  value  is  “North.” 

Audible_bell  If  enabled,  the  “bell”  command  will  produce  a  beep.  The  default  value  is  “Enabled.” 

Visible_bell  If  enabled,  the  “bell”  command  will  cause  the  screen  to  flash.  The  default  value  is 

“Enabled.” 


Root_Pattcrn  Used  to  specify  the  “pattern”  that  covers  the  background,  “on”  means  to  use  the  de¬ 
fault  desktop  gray  pattern,  “off’  means  to  not  use  the  default  desktop  gray  pattern, 
“gray”  means  to  use  a  50%  gray  color  on  color  monitors.  Anything  else  is  the  name 
of  a  file  produced  with  iconedit(l)  which  contains  an  image  that  is  replicated  all 
over  the  background.  The  default  value  is  “on.” 

After  you  have  set  the  options  you  want  in  the  “SunView”  category,  click  on  the  Save  button  in  de- 
faultsedit;  then  exit  sunview  and  restart  it. 


Select  the  “Menu”  category  to  see  the  following  items  (and  some  others): 

Stay_up  If  enabled,  menus  are  invoked  by  pressing  and  releasing  the  RIGHT  mouse  button; 

the  menu  appears  after  you  release  the  RIGHT  mouse  button.  To  chctose  a  menu  item, 
point  at  it,  then  press  and  release  the  RIGHT  mouse  button  a  second  time.  The  de¬ 
fault  value  is  “False”. 
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Iteins_iii_column_niajor 

If  enabled,  menus  that  have  more  than  one  column  are  presented  in  “column  major” 
order  (the  way  Is(lV)  presents  file  names).  This  may  make  a  large  menu  easier  to 
read.  The  default  value  is  “False.” 

After  you  have  set  the  options  you  want  in  the  “Menu”  category,  click  on  the  Save  button  in  defaultsedit. 
Any  applications  you  start  after  saving  your  changes  will  be  affected  by  your  new  choices.  For  all  defaults 
categories  except  for  “SunView”,  you  do  not  need  to  exit  sunview  and  restart  it 

The  SunView  Menu  File 

The  file  called  /usr/lib/.rootmenu  contains  the  specification  of  the  default  SunView  menu.  You  can 
change  the  SunView  menu  by  creating  your  own  file  and  giving  its  name  in  the  Rootmenu_filename  item 
in  the  SunView  Defaults. 


Lines  in  the  file  have  the  following  format:  The  left  side  is  a  menu  item  to  be  displayed,  and  the  right  side 
is  a  command  to  be  executed  when  that  menu  item  is  chosen.  You  can  also  include  comment  lines  (begin¬ 
ning  with  a  ‘#’)  and  blank  lines. 

The  menu  item  can  be  a  string,  or  the  full  pathname  of  an  icon  file  delimited  by  angle  brackets  (unless 
Walking_menus  is  disabled  in  the  SunView  defaults).  Strings  with  embedded  blanks  must  be  delimited  by 
double  quotes. 

There  are  four  reserved-word  commands  that  can  appear  on  the  right  side. 

exit  Exit  sunview  (requires  confirmation). 

REFRESH  Redraw  the  entire  screen. 

MENU  This  menu  item  is  a  pull-right  item  with  a  submenu.  If  a  full  pathname  follows 

the  MENU  command,  the  submenu  contents  are  taken  from  that  file.  Other¬ 
wise,  all  the  lines  between  a  MENU  command  and  a  matching  END  command 
are  added  to  the  submenu. 

end  Mark  the  end  of  a  nested  submenu.  The  left  side  of  this  line  should  match  the 

left  side  of  a  line  with  a  MENU  command. 

If  the  command  is  not  one  of  these  four  reserved- word  commands,  it  is  treated  as  a  command  line  and  exe¬ 
cuted.  No  shell  interpretation  is  done,  although  you  can  run  a  shell  as  a  command. 

Here  is  a  menu  file  that  demonstrates  some  of  these  features: 


Quit 

“Mail  reader" 
"My  tools" 
"Click  to  type" 
"Follow  mouse" 
"Print  selection" 
"Nested  menu" 


EXIT 

mailtool 

MENU  /home/me/mytools.menu 
swin  -c 
swin  -m 

sh  -c  get  selection  |  Ipr 
MENU 


"Command  Tool"  cmdtool 
"Shell  Tool"  shelltool 

"Nested  menu"  END 

"Icon  menu"  MENU 
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<images/textediticon>  textedit 
<images/dbxtool.icon>  dbxtool 
"Icon  menu"  END 

Multiple  Screens 

The  sunview  program  runs  on  either  a  monochrome  or  color  screen.  Each  screen  on  a  machine  with  multi¬ 
ple  screens  may  have  a  separate  sunview  running.  The  keyboard  and  mouse  input  devices  can  be  shared 
between  screens.  Using  adjacentscreens(l)  you  can  set  up  the  pointer  to  slide  from  one  sci^en  to  another 
when  you  move  it  off  the  edge  of  a  screen. 

To  set  up  an  instance  of  sunview  on  two  screens: 

•  Invoke  sunview  on  the  first  display  as  you  normally  would.  This  starts  an  instance  of  sunview  on  the 
default  frame  buffer  (/dev/fb). 

•  In  a  shelltool,  run: 

sunview  -d  device  & 

This  starts  another  device.  A  typical  choice  might  be  /dev/cgone. 

•  In  that  same  shelltool,  run: 

adjacentscreens  /dev/fb  -r  device 

This  sets  up  the  cursor  to  switch  between  screens  as  it  crosses  the  right  or  left  edge  of  the  respective 
screens. 

Multiple  Desktops  on  the  Same  Screen 

Machines  that  support  multiple  plane  groups,  such  as  the  Sun-3/110  system,  can  support  independent  sun¬ 
view  processes  on  each  plane  group.  They  can  share  keyboard  and  mouse  input  in  a  manner  similar  to  that 
for  multiple  screens.  To  set  up  two  plane  groups: 

•  Start  sunview  in  the  color  plane  group  by  running: 

sunview  -8bit_color_only  -toggleenable 

This  starts  sunview  on  the  default  frame  buffer  named  /dev/fb,  but  limits  access  to  the  color  plane 
group. 

•  In  a  shelltool,  run: 

sunview  -d  /dev/bwtwoO  -toggle_enabIe  -n  & 

This  starts  sunview  in  the  overlay  plane  accessed  by  /dev/bwtwoO. 

•  Run: 

adjacentscreens  -c  /dev/fb  ~1  /dev/bwtwoO 

This  sets  up  the  pointer  to  switch  between  desktops  as  it  crosses  the  right  or  left  edge  of  the  respective 
desktops. 

Pre-3.2  applications  cannot  be  run  on  the  -8bit_color_only  desktop,  because  they  do  not  write  to  the  over¬ 
lay  plane. 

switcher(l),  another  application  for  switching  between  desktops,  uses  some  amusing  video  wipe  anima¬ 
tion.  It  can  also  be  used  to  toggle  the  enable  plane.  See  switcher(l)  for  details. 
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Generic  Tool  Arguments 

Most  window-based  tools  take  the  following  arguments  in  their  command  lines: 


FLAG 

(LONG  FLAG) 

ARGUMENTS 

NOTES 

-Ww 

(-width) 

columns 

-Wh 

(-height) 

lines 

-Ws 

(-size) 

xy 

X  and  y  are  in  pixels 

-Wp 

(-position) 

xy 

X  and  y  are  in  pixels 

-WP 

(-icon_position) 

xy 

X  and  y  are  in  pixels 

_W1 

(-label) 

string 

-Wi 

(-iconic) 

makes  the  application  start  iconic  (closed) 

~wt 

(-font) 

filename 

-Wn 

(-no_name_stripe) 

-Wf 

(-foreground_color) 

red  green  blue 

0-255  (no  color-full  color) 

-Wb 

(-background_coIor) 

red  green  blue 

0-255  (no  color-full  color) 

-Wg 

(-set_defauIt_color) 

(apply  color  to  subwindows  too) 

-WI 

(~icon_image) 

filename 

(for  applications  with  non-default  icons) 

-WL 

(-iconjabel) 

string 

(for  applications  with  non-default  icons) 

-WT 

(-icon_font) 

filename 

(for  applications  with  non-default  icons) 

-WH 

(-help) 

print  this  table 

Each  flag  option  may  be  specified  in  either  its  short  form  or  its  long  form;  the  two  are  completely 
synonymous. 

SunView  Applications 

Some  of  the  applications  that  run  in  the  SunView  environment: 

clock(l),  cmdtool(l)»  dbxtool(l),  defau]tsedit(l),  fontedit(l)»  gfxtool(l),  iconedit(l), 
lockscreen(l),  mai]tooI(l),  overvDew(l),  perfmeter(l),  she]ltool(l), 
tektool(l),  textedit(l),  traffic(lC) 

Some  of  the  utility  programs  that  run  in  or  with  the  SunView  environment: 

adjacentscreens(l),  clearjunctions(l),  get_selection(l),  stty_from_defaults(l), 
swin(l),  switcher(l),  toolplaces(l) 

ENVIRONMENT 

DEFAULTS  FILE  The  value  of  this  environment  variable  indicates  the  file  from  which  SunView  de¬ 
faults  are  read.  When  it  is  undefined,  defaults  are  read  from  the  ^defaults  file  in 
your  home  directoi7. 

FILES 

“/.sunview 

/usr/lib/.sunview 

/usr/Hb/.rootmenu 

/usr/Iib/fonts/fixedwidthfonts/* 

/dev/wiiuc 

/dev/ptypx 

/dev/ttypjc 

/dev/fb 

/dev/kbd 

/dev/mouse 

/etc/utmp 
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SEE  ALSO 

adjacentscreens(l),  clear  Junctions(l),  clock(l),  cmdtool(l),  dbxtool(l),  defaultsedit(l),  fontedit(l), 
get_selection(l),  gfxtool(l),  iconedit(l),  lockscreen(l),  inaiUool(l),  overview(l),  perfmeter(l),  screen- 
duiiip(l),  shelltool(l),  stty_from_defaults(l),  swin(l),  switcher(l),  tektool(l),  textedit(l),  tool- 
places(l),  traffic(lC),  fbtab(5),  svdtab(5) 

BUGS 

Console  messages  ignore  window  boundaries  unless  redirected  to  a  console  window.  This  can  disrupt  the 
sunview  desktop  display.  The  display  can  be  restored  using  the  Redisplay  All  item  on  the  Sun  View  menu. 
To  prevent  this,  use  the  Console  item  to  start  a  console  window. 

With  an  optical  mouse,  sometimes  the  arrow-shaped  cursor  does  not  move  at  start-up;  moving  the  mouse  in 
large  circles  on  its  pad  normally  brings  it  to  life, 

sunview  requires  that  the  /etc/utmp  file  be  given  read  and  write  permission  for  all  users. 

On  a  color  display,  colors  may  “go  strange”  when  the  cursor  is  in  certain  windows  that  request  a  large 
number  of  colors. 

When  running  multiple  desktops,  only  one  console  window  can  be  used. 

In  Click-to-type  mode,  it  is  impossible  to  exit  from  sunview  by  typing  CTRL-D  CTRL-Q. 
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NAME 

sv_acquire,  sv_release  —  change  owner,  group,  permissions  of  window  devices 
SYNOPSIS 

sv_acquire  [  startwin  [  nwins  [  nbackground  ]]] 
sv_release 
DESCRIPTION 

sv^acquire  changes  the  owner,  group  and  permissions  of  window  system  devices  to  the  user  ID,  group  ID 
and  the  permissions  specified  in  /etc/s vdtab  (see  svdtab(5)).  if  there  is  an  entry  in  that  file.  If  no  entry  ex¬ 
ists  in  /etc/s vdtab,  no  changes  will  be  made. 

sv_release  returns  the  owner,  and  group  to  root  and  wheel.  The  permissions  are  set  as  specified  in 
/etc/svdtab. 

startwin  indicates  the  first  win  to  change,  nwins  indicates  the  number  of  windows  to  change,  nhackgound 
indicates  the  number  of  win  devices  to  change  in  the  backgound. 

This  is  a  setuid  root  program  spawned  by  the  window  system  (for  example,  sunview(l)).  sv^acquire  exits 
if  the  user  does  not  own  console  devices  listed  in  /etc/lbtab  (see  fbtab(5)).  sv_acquire  exits  with  0  on 
success  and  -1  on  failure. 

EXAMPLES 

In  the  following  example,  sv_acquire  sets  the  user  ID  and  the  group  ID  of /dev/winO  through  /dev/winl5  in 
the  foreground  and  spawns  a  background  process  to  set  /dev/winl6  through  /dev/win256  and  exit  with  er¬ 
ror  status. 

sv  acquire  0  256  240 

The  purpose  of  spawning  a  background  process  is  to  allow  the  caller  to  avoid  waiting  for  all  win  devices  to 
be  changed.  Note:  a  diskless  3/50  sets  approximately  16  wins  per  second. 

SEE  ALSO 

sunview(l),  fbtab(5),  svdtab(5) 
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NAME 

swin  -  set  or  get  SunView  user  input  options 
SYNOPSIS 

swin  [  -cghm  ]  [  -r  event  value  shift_state  ]  [  -s  event  value  shift_state  ]  [  -t  seconds  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User's  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

The  swin  (set  window;  analogous  to  stty(lV))  command  lets  you  change  some  of  the  input  behavior  of 
your  SunView  environment.  By  default,  your  keyboard  input  follows  your  pointer.  This  means  that  in  ord¬ 
er  to  type  to  a  window  you  position  the  pointer  over  the  window.  This  is  called  keyboard-follows-mouse 
mode. 

You  can  specify  that  the  keyboard  input  continues  to  go  to  the  same  window,  regardless  of  the  pointer  posi¬ 
tion,  until  you  take  some  specific  action,  like  clicking  the  mouse.  When  this  is  done,  you  can  roam  around 
the  screen  with  the  pointer  and  not  change  the  window  to  which  keyboard  input  is  directed.  Running  Sun¬ 
View  like  this  is  said  to  be  operating  in  click-tO’type  mode. 

When  running  in  click-to-type  mode,  one  user  action  sets  the  type-in  point  in  the  window  that  you  want  to 
receive  keyboard  input.  The  default  user  action  to  do  this  is  the  clicking  of  the  LEFT  mouse  button  while 
positioning  the  pointer  over  the  new  type-in  point.  This  user  action  can  be  changed. 

Another  user  action  restores  the  previous  type-in  point  in  the  window  that  you  want  to  receive  keyboard  in¬ 
put.  The  default  user  action  to  do  this  is  the  clicking  of  the  MIDDLE  mouse  button  while  positioning  the 
pointer  over  the  window.  This  user  action  can  be  changed. 

OPTIONS 

~c  Turn  on  click-to-type  mode  using  the  default  user  actions:  the  LEFT  mouse  button  sets  the  type-in 
point  and  the  MIDDLE  mouse  button  restores  the  type-in  point.  You  can  use  the  defaultsedit(l) 
program  to  set  click-to-type  on  permanently;  see  the  Click_to_Type  option  of  sunview(l). 

-g  Get  the  state  of  the  user  input  options  controlled  by  swin.  If  no  arguments  are  supplied  to  swin 
then  -g  is  implied. 

-h  Print  out  a  help  message  that  briefly  describes  the  options  to  swin. 

-m  Run  in  keyboard-follows-mouse  mode. 

-s  event  value  shift jitate 

Set  the  user  action  that  sets  the  type-in  point  and  sets  the  keyboard  input  window.  The  event 
identifies  the  particular  user  action  and  is  one  of: 

LOC_WINENTER 

pointer  entering  a  window 

MS_LEFT 

LEFT  mouse  button 

MS_MIDDLE 

MIDDLE  mouse  button 

MS_RIGHT 

RIGHT  mouse  button 


/■ 
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decimaljiumber 

place  the  decimal  number  of  a  firm  event  here;  see  list  of  events  in 
<sundev/vuid_event.h>  (avoid  function  keys,  normally  unused  control-ASCn  characters 
are  OK,  normally  unused  SHIFT  keys  are  OK). 

value  identifies  the  transition  of  the  event  and  is  one  of; 

ENTER  the  pointer  entering  a  window  (use  with  LOC_WINENTER) 

DOWN  the  button  associated  with  event  went  down 

UP  the  button  associated  with  event  went  up  (avoid  this) 

Tlie  shift_stat€  identifies  the  state  of  the  SHIFT  keys  at  the  time  of  the  event  lvalue  pair  in  order  for 
that  pair  to  be  used  to  control  the  keyboard  input  window.  The  shift  state  is  one  of: 

SHIFT_DONT_CARE 

Ignore  the  state  of  the  SHIFT  keys 

SHIFT„ALL_UP 

All  the  SHIFT  keys  must  be  up 

SHIFT_LEFT 

The  left  SHIFT  key  must  be  down  (not  the  key  labeled  LEFT) 

SHIFT_RIGHT 

the  right  SHIFT  key  must  be  down  (not  the  key  labeled  RIGHT) 

SHIFT.LEFTCTRL 

the  left  CTRL  key  must  be  down 

SHIFT„RIGHTCTRL 

the  right  CTRL  key  must  be  down 

-r  event  value  shift _state 

Set  the  user  action  that  restores  the  type-in  point  and  sets  the  keyboard  input  window.  This  user 
action  is  swallowed  so  that  the  application  that  owns  the  window  does  not  see  it.  However,  if  the 
window  already  has  keyboard  input  or  if  the  window  refuses  keyboard  input  then  this  user  action 
is  passed  on  through  to  the  application.  The  parameters  to  this  command  are  like  those  for  -s. 
The  following  example  shows  modifying  the  default  click-to-type  user  actions  so  that  a  SHIFT  left 
is  required  for  the  restore  user  event; 

example  %  swin  -c  MS  MIDDLE  DOWN  SHIFT^LEFT 

-t  seconds 

SunView  synchronizes  input  so  that  it  does  not  hand  out  the  next  user  action  until  the  application 
fielding  the  current  user  action  finishes  its  processing.  This  allows  type-ahead  and  mouse-ahead. 
If  an  applicadon  does  not  finish  processing  within  a  given  length  of  time  (process  virtual  time;  not 
wall  clock  time),  the  next  user  action  is  handed  out  anyway.  This  avoids  any  one  application  from 
hanging  the  workstation.  The  -t  command  sets  this  dme  limit.  A  seconds  value  of  0  tells  Sun- 
View  to  run  unsynchronized;  beware  of  race  conditions  in  this  mode.  The  default  seconds  value  is 
2  and  the  -c  command  makes  it  10  seconds. 

SEE  ALSO 

defaultsedit(l),  stty(lV),  sunview(l) 

SunView  User's  Guide 
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DIAGNOSTICS 

swin  not  passed  parent  window  in  environment 

swin  does  not  work  unless  SunView  is  started  already. 

BUGS 

swin  gets  you  no  help  in  preventing  you  from  specifying  -r  or  -s  parameters  that  are  not  sensible. 
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NAME 

switcher  -  switch  attention  between  multiple  SunView  desktops  on  the  same  physical  screen 
SYNOPSIS 

svi\ic\k%T[-aframe-bujfer]  [-snlllrlilolf]  [-mxy  ]  [-n]  [-eOll] 

AVAILABILITY 

This  command  is  available  with  the  SmView  User’s  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

switcher  is  used  as  an  alternative  to  adjacentscreens(l)  for  getting  between  desktops  on  the  Sun-3/1 10, 
Clicking  the  switcher  icon  gets  you  to  another  desktop  using  some  amusing  video-wipe  animation.  When 
using  walking  menus,  a  menu  is  available  to  invoke  the  switch  as  well,  switcher  can  also  be  used  to  sim¬ 
ply  set  the  enable  plane  to  0  or  1  should  it  get  out  of  wack. 

OPTIONS 

-d  frame-buffer 

The  frame  buffer  is  a  frame  buffer  device  name,  such  as  /dev/fb,  /dev/cgfour  or  /dev/bwtwoO,  on 
which  the  desktop  that  you  want  to  get  to  resides.  This  name  is  the  same  one  supplied  to  sunview. 
The  -d  flag  is  optional;  if  not  specified,  the  default  device  is  /dev/fb 

-s  n  1 1 1  r  I  i  I  o  I  f 

The  -s  flag  specifies  the  type  of  animation  used  when  switching:  n  (now),  I  (left  wipe),  r  (right 
wipe),  i  (tunnel  in),  o  (tunnel  out),  or  f  (fade).  The  -s  flag  is  optional  because  if  not  specified,  the 
default  animation  is  to  switch  immediately,  n  (now)  mode, 

-mxy  The  -m  indicates  what  the  mouse  position  should  be  on  the  destination  desktop  after  the  switch. 
An  (;r  y)  value-pair  of  (-1-1)  says  to  use  the  position  of  the  mouse  on  the  desktop  at  the  time  of 
the  switch  as  the  mouse  position  on  the  destination  desktop.  The  -m  flag  is  optional;  if  not 
specified,  the  default  is  (-1  -1). 

-n  The  -n  flag  means  no  switcher  icon  is  wanted  so  do  the  switch  right  now  and  exit  switcher  after 
the  switch.  This  is  handy  if  you  want  to  switch  from  a  root  menu  command. 

-e  0 1 1  The  -e  flag  causes  the  overlay  enable  plane  of  the  device  specified  with  the  -d  flag  to  be  set  to  ei¬ 
ther  0  (show  color)  or  1  (show  black  and  white),  switcher  run  with  this  option  has  nothing  to  do 
with  SunView,  only  the  enable  plane  is  set. 

EXAMPLE 

A  common  multiple  desktop  configuration  for  the  Sun-3/110  is  one  monochrome  and  one  color  desktop. 
You  could  set  up  an  instance  of  sunview(l)  on  each  plane  group  in  the  following  ways: 

1 .  Invoke  sunview  in  the  color  plane  group  by  running: 

example%  sunview -8bit_color_only  --toggle_enable 

This  starts  sunview  on  the  default  frame  buffer  named  /dev/lb  but  limits  access  to  the  color  plane 
group. 

2.  In  a  shelltool(l),  run: 

example%  sunview— d /dev/bwtwoO  — toggIe__enable  & 

This  starts  sunview  in  the  overlay  plane  that  is  accessed  by  /dev/bwtwoO. 
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3.  In  a  shelltool  on  the  original  desktop  run: 

exam  pie  %  switcher  “d  /dev/bwtwoO  -s  i  & 

Clicking  on  the  switcher  icon  when  it  is  visible  moves  you  to  die  /dev/bwtwoO  desktop. 

4.  In  a  shelltool  on  the  /dev/bwtwoO  desktop  run: 

example  %  switcher  ~s  o  & 

Clicking  on  the  switcher  icon  when  it  is  visible  moves  you  back  to  the  /dev/fb  desktop. 

FILES 

/usr/bin/switcher 

/dev/bwtwoO 

/dev/fb 

/dev/cgfour 

SEE  ALSO 

adjacentscreens(l)»  shelltool(l),  sunview(l) 
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NAME 

symorder  -  rearrange  a  list  of  symbols 
SYNOPSIS 

symorder  [  -s  ]  orderlist  symbolfile 
DESCRIPTION 

sysmfile  is  a  file  containing  symbols  to  be  found  in  objectfile,  1  symbol  per  line. 

objectfile  is  updated  in  place  to  put  the  requested  symbols  first  in  the  symbol  table,  in  the  order  specified. 
This  is  done  by  swapping  the  old  symbols  in  the  required  spots  with  the  new  ones.  If  all  of  the  order  sym¬ 
bols  are  not  found,  an  error  is  generated. 

This  program  was  specifically  designed  to  cut  down  on  the  overhead  of  getting  symbols  from  /vmunix. 
Sun386i  DESCRIPTION 

Symbols  specified  on  the  command  line  are  moved  to  the  beginning  of  the  output  symbol  table,  not 
swapped.  Therefore,  the  symbols  specified  on  the  command  line  will  appear  in  order  at  the  beginning  of 
the  output  symbol  table,  followed  by  the  original  symbol  table  with  the  gaps  created  by  the  moved  symbols 
closed. 

OPTIONS 

-s  Work  silently,  that  is,  display  nothing  except  error  messages.  This  is  useful  for  checking  the  error 
status. 

FILES 

/vmunix 

SEE  ALSO 

nlist(3V) 
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NAME 

sync  -  update  the  super  block;  force  changed  blocks  to  the  disk 

SYNOPSIS 

sync 

DESCRIPTION 

sync  forces  any  information  on  its  way  to  the  disk  to  be  written  out  immediately,  sync  can  be  called  to  en¬ 
sure  that  all  disk  writes  are  completed  before  the  processor  is  halted  abnormally. 

SEE  ALSO 

cron(8),  fsck(8),  halt(8),  reboot(8) 
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NAME 

sysex  -  start  the  system  exerciser 

SYNOPSIS 

sysex 


AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

sysex  is  the  system  exerciser  for  Sun386i  systems. 

This  program  is  designed  to  run  under  the  SunView  environment,  but  a  dumb  terminal  interface  is  provid¬ 
ed.  The  program  tests  subsystems  of  a  Sun386i  system,  printing  information  to  the  console  and  log  files. 
Most  commands  are  accessible  by  way  of  buttons,  toggle  switches,  or  menus.  A  startup  file  "/.sysexrc,  can 
be  created  by  experienced  users  to  set  runtime  parameters. 

USAGE 

Subwindows 

Control  Panel 

Perfmon  window 
Console  window 
Status  Window 


Tells  which  version  of  the  exerciser  is  running.  User  controls  sysex  executions  through 
the  toggles,  buttons,  and  sliders  in  this  panel. 

Graphically  displays  system  statics.  The  standard  SunView  perfmeter(l). 

Displays  the  system  messages  and  sysex  error  messages. 

Displays  pass  counts  and  error  counts  for  all  tests  that  are  currently  selected.  Also 
displays  system  pass  count,  and  total  system  errors.  Elapsed  time  signifies  time  since 
start  button  is  pressed. 


Load  Sliders 

These  slide  bars  allow  the  user  to  modulate  the  load  on  the  system. 

I/O-CPU  Load 

Moving  this  slider  changes  the  balance  between  I/O-intensive  and  compute-intensive  tests  that  are 
running. 


SYSTEMLOAD 

Moving  this  slider  increases  and  decreases  the  system  activity  generated  by  sysex. 

Test  Toggles 

Each  test  selection  on  the  control  panel  is  selectable  by  moving  the  cursor  over  to  the  toggle  and  pressing 
the  left  mouse  button. 


The  tests  are  displayed  by  device  groups  in  the  control  panel.  A  test  is  enabled  when  a  check  mark  is  seen 
in  the  box.  Clicking  left  on  the  group  label  acts  as  a  group  enable/disable  for  all  tests  in  that  device  group. 
Currendy  there  are  tests  for  physical  memory  and  virtual  memory,  fixed  disk,  diskette,  Ethernet,  and  color 
frame  buffer. 


Command  Buttons 
Command  buttons 

Quit  Sysex 

Log  Files 

Options 

Print  Screen 


exist  for  the  following  commands: 

Stop  all  current  tests  and  exit  the  exerciser.  All  logs  will  be  saved. 
Display  menu  for  choosing  a  log  to  view,  reset,  or  print. 

Display  window  through  which  V.sysexrc  parameters  can  be  modified. 
Take  screendump  of  the  current  screen. 
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Start  Tests  Start  all  test  from  passO  that  have  been  selected.  Resets  pass  count.  Toggles  to  Stop 
Tests.  Begin  elapsed  time  count. 

Stop  Tests  Stop  all  tests  that  are  running.  Toggles  to  Start  Tests. 

Pause  Pause  tests  by  issuing  SIGSTP. 


Continue  Continue  testing  from  the  stopped  state  without  resetting  pass  count.  Toggles  to 

Pause,leaves  pass  counts  intact.  Continue  elapsed  time  count  if  Continued  from  a  Pause. 


Logs 

When  the  user  selects  the  DISPLAY  LOGS  button  and  chooses  from  the  log  menu,  a  scrollable  pop-up  win¬ 
dow  displays  the  log,  which  is  one  of  /var/sysex/sysex.info,  /var/sysex/sysex.error,  or 
/etc/adm/messages.  Logs  contain  messages  classified  as  INFO,  WARNING,  ERROR,  or  FATAL.  The  INFO 
file  contains  all  messages;  the  ERROR  file  contains  only  error  and  fatal  messages. 

Variables 

sysex  has  several  variables  than  can  be  set  in  the  7.sysexrc  file.  Some  of  the  variables  pertain  to  only  one 
test  and  others  are  global  to  all  tests.  Clicking  Done  saves  changes  to  the  "/.sysexrc  file.  Clicking  Cancel 
leaves  options  unchanged. 


verbose  Display  messages  about  what  is  currently  taking  place, 
verify  Run  through  a  cursory  pass  of  tests  to  see  all  subsystems  present. 


run_on_err 

Halt  subsystem  testing  when  an  error  occurs. 
sysex_haU_on_err 

Stop  sysex  if  an  error  occurs  in  any  subsystem, 
core  Create  core  dump  in  Ivarl sysex. 
single_pass 

Run  one  pass  of  each  selected  device  test. 

For  the  expert  user,  more  commands  are  available  by  clicking  the  manufacturing  cycle  to  Enabled.  This 
displays  the  following  options: 

fdc_wait  Variable  wait  time  between  executions  of  the  diskette  test 
vmem_wait 

Variable  delay  between  successive  executions  of  the  virtual  memory  test 
debug  Display  all  messages  to  aid  analysis  of  problem  systems. 
check_eeprom 

Read  NVRAM  configuration  information  and  display  values, 
intervention 

Turn  on  or  off  the  confirmer  for  all  destructive  tests,  or  for  tests  requiring  media. 

FILES 

/usr/sysex/sysex 
/var/sysex/core 
/  var/sysex/sysex.info 
/var/sysex/sysex*error 
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NAME 

syswait  —  execute  a  command,  suspending  termination  until  user  input 
SYNOPSIS 

syswait  message  command 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0 jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

syswait  executes  a  specified  command,  suspending  termination  until  the  user  types  any  character,  message 
is  the  message  prompting  the  user  to  type  a  character  to  terminate  the  command,  command  is  the  command 
to  be  executed. 

EXAMPLE 

The  following  example  invokes  a  cmdtool  and  executes  ‘Is  *.c’,  but  waits  for  the  user  to  type  a  character 
before  terminating  the  Is  and  closing  the  cmdtool  window. 

cmdtool  syswait  "Press  any  key  to  quit . . "Is  *.c"  & 
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NAME 

tabs  -  set  tab  stops  on  a  terminal 
SYNOPSIS 

/usr/Sbin/tabs  [  tabspec  ]  [  -Ttype  ]  [  +m/i  ] 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

tabs  can  be  used  to  specify  TAB  stops  on  terminals  that  support  remotely-settable  hardware  TAB  charac¬ 
ters.  TAB  stops  are  set  according  to  the  tabspec  option,  as  described  below,  and  previous  settings  are 
erased. 

Four  types  of  tab  specification  are  accepted  for  tabspec.  They  are: 

-code  Set  the  TAB  stops  according  to  the  canned  TAB  setting  specified  by  code ,  as  given  by  fspec(5). 

-n  Set  the  TAB  stops  at  intervals  of  n  columns,  that  is,  at  l+/i,  1+2* n,  and  so  on,  as  per  the  -n 

specification  as  given  by  fspec(5). 

nl,n2,... 

Set  the  TAB  stops  at  positions  ni ,  n2,  and  so  on,  as  per  the  nl,n2,...  specification  as  given  by 
fspec(5). 

-—file  Read  the  first  line  of  the  file  specified  by  file,  searching  for  a  format  specification  as  given  by 
fspec(5).  If  this  line  contains  a  format  specification,  set  the  TAB  stops  accordingly,  otherwise  set 
them  to  every  8  columns.  This  type  of  specification  may  be  used  to  make  sure  that  a  file  contain¬ 
ing  a  TAB  specification  is  displayed  with  correct  TAB  settings.  For  example,  it  can  be  used  with 
the  pr(lV)  command: 

tabs  — file;  pr  file 

If  no  tabspec  is  given,  the  default  value  is  -8,  the  standard  default  TAB  setting.  The  lowest  column  number 
is  1.  Note:  for  tabs,  column  1  always  refers  to  the  leftmost  column  on  a  terminal,  even  one  whose  column 
markers  begin  at  0,  (such  as  the  DASI  300,  DASI  300s,  and  DASI  450).  TAB  and  margin  setting  is  per¬ 
formed  by  echoing  to  the  proper  sequences  to  the  standard  output. 

OPTIONS 

-Ttype  tabs  usually  needs  to  know  the  type  of  terminal  in  order  to  set  TAB  characters,  and  always  needs 
to  know  to  set  margins,  type  is  a  name  listed  in  tenn(5).  If  no  ~T  flag  is  supplied,  tabs  uses  the 
value  of  the  environment  variable  TERM.  If  TERM  is  not  defined  in  the  environment  (see 
environ(5V)),  tabs  tries  a  default  sequence  that  will  work  for  many  terminals. 

+mrt  The  margin  argument  may  be  used  for  some  terminals.  It  moves  all  TAB  stops  over  n  columns  by 
making  column  n+\  the  left  margin.  If  +m  is  given  without  a  value  of  n,  the  value  assumed  is  10, 
For  a  TermiNet,  the  first  value  in  the  tab  list  should  be  1,  or  the  margin  will  move  even  further  to 
the  right.  The  normal  (leftmost)  margin  on  most  terminals  is  obtained  by  +m0.  The  margin  for 
most  terminals  is  reset  only  when  the  +m  flag  is  given  explicitly. 

SEE  ALSO 

pr(lV),  tput(lV),  environ(5V),  fspec(5),  term(5),  terminfo(5V) 
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BUGS 

There  is  no  consistency  between  different  terminals  regarding  ways  of  clearing  tabs  and  setting  the  left 
margin. 

tabs  clears  only  20  tabs  (on  terminals  requiring  a  long  sequence),  but  is  willing  to  set  64. 
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NAME 

tail  -  display  the  last  part  of  a  file 
SYNOPSIS 

tail  +  \ -number  [  Ibc  ]  [  f  ]  [filename  ] 
tail  +  \-number  [  1  ]  [  rf  ]  [filename  ] 

DESCRIPTION 

tail  copies  filename  to  the  standard  output  beginning  at  a  designated  place.  If  no  file  is  named,  the  standard 
input  is  used. 

OPTIONS 

Options  are  all  jammed  together,  not  specified  separately  with  their  own  signs. 

+ number 

Begin  copying  at  distance  number  from  the  beginning  of  the  file,  number  is  counted  in  units  of 
lines,  blocks  or  characters,  according  to  the  appended  option  I,  b,  or  c.  When  no  units  are 
specified,  counting  is  by  lines.  If  number  is  not  specified,  the  value  10  is  used. 

—number 

Begin  copying  at  distance  number  from  the  end  of  the  file,  number  is  counted  in  units  of  lines, 
blocks  or  characters,  according  to  the  appended  option  1,  b,  or  c.  When  no  units  are  specified,* 
counting  is  by  lines.  If  number  is  not  specified,  the  value  10  is  used. 

1  number  is  counted  in  units  of  lines. 

b  number  is  counted  in  units  of  blocks. 

c  number  is  counted  in  units  of  characters. 

r  Copy  lines  from  the  end  of  the  file  in  reverse  order.  The  default  for  option  r  is  to  print  the  entire 
file  in  reverse  order,  number  is  the  count  of  lines  from  the  end  of  the  file  regardless  of  sign.  Op¬ 
tion  r  may  not  be  used  with  b  or  c. 

f  If  the  input  file  is  not  a  pipe,  do  not  terminate  after  the  line  of  the  input  file  has  been  copied,  but 
enter  an  endless  loop,  sleeping  for  a  second  and  then  attempting  to  read  and  copy  further  records 
from  the  input  file.  This  option  may  be  used  to  monitor  the  growth  of  a  file  that  is  being  written 
by  some  other  process.  For  example,  the  command: 

tail  -f  fred 

will  print  the  last  ten  lines  of  the  file  fred,  followed  by  any  lines  that  are  appended  to  fred 
between  the  time  tail  is  initiated  and  killed.  As  another  example,  the  command: 

tail  -15cf  fred 

will  print  the  last  15  characters  of  the  file  fred,  followed  by  any  lines  that  are  appended  to  fred 
between  the  time  tail  is  initiated  and  killed. 

SEE  ALSO 

dd(l) 

BUGS 

Data  for  a  tail  relative  to  the  end  of  the  file  is  stored  in  a  buffer,  and  thus  is  limited  in  size. 

Various  kinds  of  anomalous  behavior  may  happen  with  character  special  files. 
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NAME 

talk  -  talk  to  another  user 
SYNOPSIS 

talk  username  [  ttyname  ] 

DESCRIPTION 

talk  is  a  visual  communication  program  which  copies  lines  from  your  terminal  to  that  of  another  user. 

If  you  wish  to  talk  to  someone  on  your  own  machine,  then  username  is  just  the  person’s  login  name.  If  you 

wish  to  talk  to  a  user  on  another  host,  then  username  is  one  of  the  following  forms  : 
hostluser 
host. user 
hostluser 
user@host 

though  user@host  is  perhaps  preferred. 

If  you  want  to  talk  to  a  user  who  is  logged  in  more  than  once,  the  ttyname  argument  may  be  used  to  indi¬ 
cate  the  appropriate  terminal  name. 

When  first  called,  talk  sends  the  message: 


Message  from  Tn\kX)stemon@his_machinesiUime . , . 
talk:  connection  requested  hy  yourjiame@yourjnachine , 
talk:  respond  with:  talk  your  jiame@your_machine 
to  the  user  you  wish  to  talk  to.  At  this  point,  the  recipient  of  the  message  should  reply  by  typing: 

example  %  talk  yourjiame@yourjnachine 

It  does  not  matter  from  which  machine  the  recipient  replies,  as  long  as  their  login  name  is  the  same.  Once 
communication  is  established,  the  two  parties  may  type  simultaneously,  with  their  output  appearing  in 
separate  windows.  Typing  CTRL-L  redraws  the  screen,  while  your  erase,  kill,  and  word  kill  characters 
will  work  in  talk  as  normal.  To  exit,  just  type  your  interrupt  character;  talk  then  moves  the  cursor  to  the 
bottom  of  the  screen  and  restores  the  terminal. 

Permission  to  talk  may  be  denied  or  granted  by  use  of  the  mesg  command.  At  the  outset  talking  is  allowed. 
Certain  commands,  in  particular  nroff(l)  and  pr(l  V)  disallow  messages  in  order  to  prevent  messy  output. 

FILES 

/etc/hosts  to  find  the  recipient’s  machine 

/etc/utmp  to  find  the  recipient’s  tty 

SEE  ALSO 

mail(l),  mesg(l),  nroff(l),  pr(l  V),  who(l),  write(l),  talkd(8C) 
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NAME 

tar  -  create  tape  archives,  and  add  or  extract  files 

SYNOPSIS 

tar  [  -  ]  c  I  r  1 1 1  u  I X  [  bBeflFhilmopvwX014578  ]  [  tarjile  ]  [  blocksize  ]  [  exclude-file  ]  [  -I  include-file  ] 
filenamel  filename2  . . .  — C  directory  filenameN . . . 

DESCRIPTION 

tar  archives  and  extracts  multiple  files  onto  a  single  tar,  file  archive,  called  a  tarjile,  A  tarfile  is  usually  a 
magnetic  tape,  but  it  can  be  any  file,  tar’s  actions  are  controlled  by  the  first  argument,  the  a  string  of 
characters  containing  exactly  one  function  letter  from  the  set  crtux,  and  one  or  more  of  the  optional  func¬ 
tion  modifiers  listed  below.  Other  arguments  to  tar  are  file  or  directory  names  that  specify  which  files  to 
archive  or  extract.  In  all  cases,  the  appearance  of  a  directory  name  refers  recursively  to  the  files  and  sub¬ 
directories  of  that  directory. 

FUNCTION  LETTERS 

c  Create  a  new  tarjile  and  write  the  named  files  onto  it. 

r  Write  the  named  files  on  the  end  of  the  tarjile.  Note:  this  option  does  not  work  with  quarter-inch 
archive  tapes. 

t  List  the  table  of  contents  of  the  tarjile. 

u  Add  the  nam^  files  to  the  tarjile  if  they  are  not  there  or  if  they  have  been  modified  since  they 
were  last  archived.  Note:  this  option  does  not  work  with  quarter-inch  archive  tapes. 

X  Extract  the  named  files  from  the  tarjile .  If  a  named  file  matches  a  directory  with  contents  written 
onto  the  tape,  this  directory  is  (recursively)  extracted.  The  owner,  modification  time,  and  mode 
are  restored  (if  possible).  If  no  filename  arguments  are  given,  all  files  in  the  archive  are  extracted. 
Note:  if  multiple  entries  specifying  the  same  file  are  on  the  tape,  the  last  one  overwrites  all  earlier 
versions. 

FUNCTION  MODIFIERS 

b  Use  the  next  argument  as  the  blocking  factor  for  tape  records.  The  default  blocking  factor  is  20 
blocks.  The  block  size  is  determined  automatically  when  reading  tapes  (key  letters  x  and  t).  This 
determination  of  the  blocking  factor  may  be  fooled  when  reading  from  a  pipe  or  a  socket  (see  the 
B  key  letter  below).  The  maximum  blocking  factor  is  determined  only  by  the  amount  of  memory 
available  to  tar  when  it  is  run.  Larger  blocking  factors  result  in  better  throughput,  longer  blocks 
on  nine-track  tapes,  and  better  media  utilization. 

B  Force  tar  to  perform  multiple  reads  (if  necessary)  so  as  to  read  exactly  enough  bytes  to  fill  a 
block.  This  option  exists  so  that  tar  can  work  across  the  Ethernet,  since  pipes  and  sockets  return 
partial  blocks  even  when  more  data  is  coming. 

e  If  any  unexpected  errors  occur  tar  will  exit  immediately  with  a  positive  exit  status. 

f  Use  the  next  argument  as  the  name  of  the  tarjile.  If  f  is  omitted,  use  the  device  indicated  by  the 

TAPE  environment  variable,  if  set.  Otherwise,  use  /dev/rmtS  by  default.  If  tarjile  is  given  as 
tar  writes  to  the  standard  output  or  reads  from  the  standard  input,  whichever  is  appropriate.  Thus, 
tar  can  be  used  as  the  head  or  tail  of  a  filter  chain,  tar  can  also  be  used  to  copy  hierarchies  with 
the  command; 

example%  cd  fromdir;  tar  cf  - .  |  (cd  todir;  tar  xfBp  -) 

F  With  one  F  argument  specified,  exclude  all  directories  named  SCCS  from  tarjile.  With  two  argu¬ 
ments  FF,  exclude  all  directories  named  SCCS,  all  files  with  .o  as  their  suffix,  and  all  files  named 
errs,  core,  and  a.out. 

h  Follow  symbolic  links  as  if  they  were  normal  files  or  directories.  Normally,  tar  does  not  follow 
symbolic  links. 

i  Ignore  directory  checksum  errors. 
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1  Display  error  messages  if  all  links  to  archived  files  cannot  be  resolved.  If  I  is  not  used,  no  error 
messages  are  printed. 

m  Do  not  extract  modification  times  of  extracted  files.  The  modification  time  will  be  the  time  of 
extraction. 

o  Suppress  information  specifying  owner  and  modes  of  directories  which  tar  normally  places  in  the 
archive.  Such  information  makes  former  versions  of  tar  generate  an  error  message  like: 

filename/:  cannot  create 

when  they  encounter  it 

p  Restore  the  named  files  to  their  original  modes,  ignoring  the  present  umask(2V).  SetUID  and 
sticky  information  are  also  extracted  if  you  are  the  super-user.  This  option  is  only  useful  with  the 
X  key  letter. 

V  Verbose,  Normally  tar  does  its  work  silently;  this  option  displays  the  name  of  each  file  tar  treats, 
preceded  by  the  function  letter.  When  used  with  the  t  function,  v  displays  the  tarfile  entries  in  a 
form  similar  to  *ls  -V. 

w  Wait  for  user  confirmation  before  taking  the  specified  action.  If  you  use  w,  tar  displays  the  action 
to  be  taken  followed  by  the  file  name,  and  then  waits  for  a  y  response  to  proceed.  No  action  is 
taken  on  the  named  file  if  you  type  anything  other  than  a  line  beginning  with  y. 

X  Use  the  next  argument  as  a  file  containing  a  list  of  named  files  (or  directories)  to  be  excluded  from 
the  tarfile  when  using  the  key  letters  c,  x,  or  t.  Multiple  X  arguments  may  be  used,  with  one 
exclude  file  per  argument. 

014578  Select  an  alternate  drive  on  which  the  tape  is  mounted.  The  numbers  2,  3,  6,  and  9  do  not  specify 
valid  drives.  The  default  is  /dev/rmt8. 

If  a  file  name  is  preceded  by  -I  then  the  filename  is  opened.  A  list  filenames,  one  per  line,  is  treated  as  if 
each  appeared  separately  on  the  command  line.  Be  careful  of  trailing  white  space  in  both  include  and 
exclude  file  lists. 

In  the  case  where  excluded  files  (see  X  option)  also  exist,  excluded  files  take  precedence  over  all  included 
files.  So,  if  a  file  is  specified  in  both  the  include  and  exclude  files  (or  on  the  command  line),  it  will  be 
excluded. 

If  a  file  name  is  preceded  by  -C  in  a  c  (create)  or  r  (replace)  operation,  tar  will  perform  a  chdir  (see 
csh(l))  to  that  file  name.  This  allows  multiple  directories  not  related  by  a  close  common  parent  to  be 
archived  using  short  relative  path  names.  See  EXAMPLES  below. 

Note:  the  -C  option  only  applies  to  one  following  directory  name  and  one  following  file  name. 

EXAMPLES 

To  archive  files  from  /usr/include  and  from  /etc,  one  might  use: 

example  %  tar  c  ~C  /usr  include  -C  /etc  . 

If  you  get  a  table  of  contents  from  the  resulting  tarfile,  you  will  see  something  like: 

include/ 

include/a,out.h 

and  all  the  other  files  in  /usr/include . . . 

/chown 

and  all  the  other  files  in  /etc 


Sun  Release  4.1 


Last  change:  16  February  1988 


563 


TAR(l) 


USER  COMMANDS 


TAR(l) 


Here  is  a  simple  example  using  tar  to  create  an  archive  of  your  home  directory  on  a  tape  mounted  on  drive 

/dev/rmtO: 

example  %  cd 

example  %  tar  cvf  /dev/rmtO  . 

messages  from  tar 

The  c  option  means  create  the  archive;  the  v  option  makes  tar  tell  you  what  it  is  doing  as  it  works;  the  f 
option  means  that  you  are  specifically  naming  the  file  onto  which  the  archive  should  be  placed  (/dev/rmtO 
in  this  example). 

Now  you  can  read  the  table  of  contents  from  the  archive  like  this: 

example  %  tar  tvf  /dev/rmtO  display  table  of  contents  of  the  archive 

{access  user-id/ group-id  size  mod.  date  filename) 

rw-r-r- 1677/40  2123  Nov  7 18:15:1985  yarchive/test.c 

example  % 

You  can  extract  files  from  the  archive  like  this: 

example  %  tar  xvf  /dev/rmtO  extract  files  from  the  archive 

messages  from  tar 

example  % 

If  there  are  multiple  archive  files  on  a  tape,  each  is  separated  from  the  following  one  by  an  EOF  marker, 
tar  does  not  read  the  EOF  mark  on  the  tape  after  it  finishes  reading  an  archive  file  because  tar  looks  for  a 
special  header  to  decide  when  it  has  reached  the  end  of  the  archive.  Now  if  you  try  to  use  tar  to  read  the 
next  archive  file  from  the  tape,  tar  does  not  know  enough  to  skip  over  the  EOF  mark  and  tries  to  read  the 
EOF  mark  as  an  archive  instead.  The  result  of  this  is  an  error  message  from  tar  to  the  effect: 

tar:  blocksize=0 

This  means  that  to  read  another  archive  from  the  tape,  you  must  skip  over  the  EOF  marker  before  starting 
another  tar  command.  You  can  accomplish  this  using  the  mt(l)  command,  as  shown  in  the  example 
below.  Assume  that  you  are  reading  from  /dev/nrmtO. 

example%  tar  xvfp  /dev/nrmtO  read  first  archive  from  tape 

messages  from  tar 

example%  mt  fsf  1  skip  over  the  end-of-file  marker 

example^  tar  xvfp  /dev/nrmtO  read  second  archive  from  tape 

messages  from  tar 

example  % 

Finally,  here  is  an  example  using  tar  to  transfer  files  across  the  Ethernet.  First,  here  is  how  to  archive  files 
from  the  local  machine  (example)  to  a  tape  on  a  remote  system  (host): 

example^  tar  cvfb  -  20  filenames  \  rsh  host  dd  of=/dev/rmt0  obs=20b 

messages  from  tar 

example% 

In  the  example  above,  we  are  creating  a  tarfile  with  the  c  key  letter,  asking  for  verbose  output  from  tar 
with  the  v  option,  specifying  the  name  of  the  output  tarfile  using  the  f  option  (the  standard  output  is  where 
the  tarfile  appears,  as  indicated  by  the  sign),  and  specifying  the  blocksize  (20)  with  the  b  option.  If  you 
want  to  change  the  blocksize,  you  must  change  the  blocksize  arguments  both  on  the  tar  command  and  on 
the  dd  command. 

Now,  here  is  how  to  use  tar  to  get  files  from  a  tape  on  the  remote  system  back  to  the  local  system: 
example  %  rsh  -n  host  dd  if=/dev/rmtO  bs=20b  |  tar  xvBfb  -  20  filenames 
messages  from  tar 
example  % 


w 


564 


Last  change:  16  February  1988 


Sun  Release  4.1 


TAR(l) 


USER  COMMANDS 


TAR(l) 


i 


In  the  example  above,  we  are  extracting  from  the  tarfile  with  the  x  key  letter,  asking  for  verbose  output 
from  tar  with  the  v  option,  telling  tar  it  is  reading  from  a  pipe  with  the  B  option,  specifying  the  name  of 
the  input  tarfile  using  the  f  option  (the  standard  input  is  where  the  tarfile  appears,  as  indicated  by  the 
sign),  and  specifying  the  blocksize  (20)  with  the  b  option. 

FTLES 

/dev/rmt?  half-inch  magnetic  tape  interface 

/dev/rst?  SCSI  tape  interface 

/tmp/tar* 

ENVIRONMENT 

TAPE  If  specified,  in  the  environment,  the  value  of  TAPE  indicates  the  default  tape  device. 

SEE  ALSO 

cpio(l),  csh(l),  mt(l),  umask(2V),  tar(5),  dump(8),  restore(8) 

BUGS 

Neither  the  r  option  nor  the  u  option  can  be  used  with  quarter-inch  archive  tapes,  since  these  tape  drives 
cannot  backspace. 

There  is  no  way  to  ask  for  the  nth  occurrence  of  a  file. 

Tape  errors  are  handled  ungracefully. 

The  u  option  can  be  slow. 

There  is  no  way  selectively  to  follow  symbolic  links. 

When  extracting  tapes  created  with  the  r  or  u  options,  directory  modification  times  may  not  be  set 
correctly. 

Files  with  names  longer  than  100  characters  cannot  be  processed. 

Filename  substitution  wildcards  do  not  work  for  extracting  files  from  the  archive.  To  get  around  this,  use  a 
command  of  the  form: 

tar  xvf. . .  /dev/rstO  ‘tar  tf. . .  /dev/rstO  1  grep  "pattern 


Sun  Release  4.1 


Last  change:  16  February  1988 


565 


TBL(l) 


USER  COMMANDS 


TBL(l) 


NAME 

tbl  -  format  tables  for  nroff  or  troff 
SYNOPSIS 

tbl  [  -ms  ]  [filename  ] . . . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  in¬ 
formation  on  how  to  install  optional  software. 

DESCRIPTION 

tbl  is  a  preprocessor  for  formatting  tables  for  iiroff(l)  or  troff(l).  The  input  filenames  are  copied  to  the 
standard  output,  except  that  lines  between  .TS  and  .TE  command  lines  are  assumed  to  describe  tables  and 
are  reformatted.  Details  are  given  in  Formatting  Documents. 

If  no  arguments  are  given,  tbl  reads  the  standard  input,  so  tbl  may  be  used  as  a  filter.  When  tbl  is  used 
with  eqn(l)  or  neqn  the  tbl  command  should  be  first,  to  minimize  the  volume  of  data  passed  through  pipes. 

OPTIONS 

-ms  Copy  the  -ms  macro  package  to  the  front  of  the  output  file. 

EXAMPLE 

As  an  example,  letting  \t  represent  a  TAB  (which  should  be  typed  as  a  genuine  TAB)  the  input 

.TS 

css 

CCS 

c  c  c 

1  n  n. 

Household\tPopulation 
T  ownMHouseholds 
\tNumber\tSize 
Bedminster\t789\t3.26 
Bernards  Twp.\t3087\t3.74 
Bernards  ville\t2018\t3.30 
Bound  Brook\t3425\t3.04 
Branchburg\tl644\t3.49 
Bridgewater\t7897\t3.81 
Far  Hills\t240\t3.19 
.TE 


yields 


Household  Population 
Town  Households 


Number 

Size 

Bedminster 

789 

3.26 

Bernards  Twp. 

3087 

3.74 

Bernardsville 

2018 

3.30 

Bound  Brook 

3425 

3.04 

Branchburg 

1644 

3.49 

Bridgewater 

7897 

3.81 

Far  Hills 

240 

3.19 

566 


Last  change:  21  December  1987 


Sun  Release  4.1 


TBL(l) 


USER  COMMANDS 


TBL(l) 


SEE  ALSO 

eqii(l),  nroff(l),  troff(l) 
Formatting  Documents 
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NAME 

tcopy  -  copy  a  magnetic  tape 
SYNOPSIS 

tcopy  source  [  destination  ] 

DESCRIPTION 

tcopy  copies  the  magnetic  tape  mounted  on  the  tape  drive  specified  by  the  source  argument  The  only  as¬ 
sumption  made  about  the  contents  of  a  tape  is  that  there  are  two  tape  marks  at  the  end. 

When  only  a  source  drive  is  specified,  tcopy  scans  the  tape,  and  displays  information  about  the  sizes  of 
records  and  tape  files.  If  a  destination  is  specified,  tcopy  makes  a  copies  the  source  tape  onto  the  destina¬ 
tion  tape,  with  blocking  preserved.  As  it  copies,  tcopy  produces  the  same  output  as  it  does  when  only 
scanning  a  tape. 

SEE  ALSO 

int(l) 
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NAME 

tcov  -  construct  test  coverage  analysis  and  statement-by-statement  profile 
SYNOPSIS 

tcov  [  -a  ]  [  -n  ]  srcjile. . . 

AVAILABILITY 

This  command  is  available  on  Sun-3  and  Sun-4  systems  only. 

DESCRIPTION 

tcov  produces  a  test  coverage  analysis  and  statement-by-statement  profile  of  a  C  or  FORTRAN  program. 
When  a  program  in  a  file  named  ^ie.c  ot  file  S  is  compiled  with  the  -a  option,  a  corresponding  ^/e.d  file  is 
created.  Each  time  the  program  is  executed,  test  coverage  information  is  accumulated  in  file  A, 

tcov  takes  source  files  as  arguments.  It  reads  the  corresponding ^/e.d  file  and  produces  an  annotated  listing 
of  the  program  with  coverage  data  in  .tcov.  Each  straight-line  segment  of  code  (or  each  line  if  the  -a 
option  to  tcov  is  specified)  is  prefixed  with  the  number  of  times  it  has  been  executed;  lines  which  have  not 
been  executed  are  prefixed  with  #####. 

Note:  the  profile  produced  includes  only  the  number  of  times  each  statement  was  executed,  not  execution 
times;  to  obtain  times  for  routines  use  gprof(l)  or  prof(l). 

OPTIONS 

—a  Display  an  execution  count  for  each  statement;  if  —a  is  not  specified,  an  execution  count  is 
displayed  only  for  the  first  statement  of  each  straight-line  segment  of  code. 

—n  Display  table  of  the  line  numbers  of  the  n  most  frequently  executed  statements  and  their  execution 
counts. 

EXAMPLES 

The  command: 

example  %  cc  -a  -o  prog  prog.c 
compiles  with  the  -a  option  —  produces  prog.d 
The  command:  example  %  prog 
executes  the  program  accumulates  data  in  prog.d 
The  command: 

example%  tcov  prog.c  produces  an  annotated  listing  in  file  prog.tcov 

FILES 

file.c  input  C  program  file 

input  FORTRAN  program  file 
file.d  input  test  coverage  data  file 

file.tcov  output  test  coverage  analysis  listing  file 

/usr/lib/bb_link.o  entry  and  exit  routines  for  test  coverage  analysis 
SEE  ALSO 

cc(lV),  gprof(l),  prof(l),  exit(2V) 

DIAGNOSTICS 

premature  end  of  file 

Issued  for  routines  containing  no  statements. 

BUGS 

The  analyzed  program  must  call  exit(2V)  or  return  normally  for  the  coverage  information  to  be  saved  in 
the  .d  file. 
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NAME 

tee  -  replicate  the  standard  output 
SYNOPSIS 

tee  [  -ai  ]  [filename  ] . , . 

DESCRIPTION 

tee  transcribes  the  standard  input  to  the  standard  output  and  makes  copies  in  the  filenames. 
OPTIONS 

-a  Append  the  output  to  ih&filenames  rather  than  overwriting  them. 

-i  Ignore  interrupts. 
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NAME 

tektool  -  Sun  View  Tektronix  4014  terminal-emulator  window 
SYNOPSIS 

tektool  [  -s[  Icdeg[  ce  ]in[  12  ]  ]  [  -[  cr  ]  command-line  ]  [  -ffontdir  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

tektool  emulates  a  Tektronix  4014  terminal  with  the  enhanced  graphics  module.  It  does  this  in  much  the 
same  way  as  shelltool  (see  shelltool(l))  emulates  a  regular  glass  tty.  When  tektool  is  invoked,  a  command 
(usually  a  shell)  is  started  up,  its  output  and  input  are  connected  to  the  emulator,  and  a  new  window  is 
formed.  The  default  window  is  the  entire  screen.  When  the  emulator  is  running,  keys  TF(1)  through  TF(3), 
(usually  function  keys  FI  -F3  (see  kbd(4S))  have  special  meaning. 

TF  (1)  Unshifted,  this  is  the  4014  PAGE  button.  Shifted,  this  is  the  4014  RESET  button. 

(2)  Copy  screen.  The  raster  image  (<rasteHile.h>)  of  the  4014  screen  is  piped  to  a  com¬ 

mand  found  in  the  TEKCOPY  environment  variable.  If  TEKCOPY  is  not  found  in  the 
environment,  ‘Ipr  -v’  is  used.  The  copy  button  is  unaffected  by  window  manipulations, 
and  will  transmit  the  contents  of  the  4014  screen  only. 

TF  (3)  Release  page  full  condition. 

These  functions  are  also  available  through  the  tool  menu.  When  in  graphics  input  (GIN)  mode  and  the 
4014  crosshairs  are  visible,  the  left  hand  mouse  button  may  be  used  as  the  space  bar  to  terminate  GIN 
mode. 

OPTIONS 

“S  Specifies  the  Tektronix  4014  strap  options  with  the  following  modifiers: 

1  Received  LINEFEED  characters  also  generate  RETURN  characters, 
c  Received  RETURN  characters  also  generate  LINEFEED  characters, 
d  Received  DELETE  characters  are  used  as  low  order  Y  axis  ( LOY )  addresses, 
e  Echo  keyboard  input. 

g  Graphic  input  mode  (GIN)  terminator  specification.  If  this  strap  is  followed  by  a  c, 
GIN  mode  data  is  terminated  by  a  RETURN  character.  If  it  is  followed  by  a  e,  GIN 
mode  data  is  terminated  by  a  RETURN  character  followed  by  an  EOT  character.  If 
this  strap  is  not  present,  no  characters  are  sent  after  GIN  mode  data, 
m  Page  full  control  specification.  If  this  strap  is  followed  by  a  1,  tektool  will  stop 
accepting  tty  input  when  a  LINEFEED  character  is  done  past  the  last  line  in  margin 
1.  This  is  the  4014  page  full  condition.  The  page  full  condition  it  released  by  a 
PAGE  or  a  RELEASE  or  any  ASCII  keyboard  input.  If  this  strap  is  followed  by  a  2, 
the  page  full  condition  happens  at  the  end  of  margin  2.  If  this  strap  is  not  present, 
the  page  full  condition  never  occurs. 

If  the  -s  option  is  not  given,  the  environment  is  searched  for  the  TEKSTRAPS  vari¬ 
able  which  provides  the  modifiers.  The  straps  may  also  be  set  by  the  property  sheet 
available  by  selecting  the  PROPS  menu  item.  If  no  straps  are  specified  the  d  strap 
is  assumed. 

“C  command-line  Take  terminal  emulator  input  from  a  shell  which  in  turn  runs  the  command-line  follow¬ 
ing  the  --c  option. 
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-f fontdir  Look  for  fonts  in  the  directory  specified  hy  font4ir.  The  fonts  must  be  called  tekfontO 

through  tekfontS.  Fonts  must  be  in  vfont(5)  format.  If  this  option  is  not  given,  the  font 
directory  is  obtained  from  the  TEKFONTS  environment  variable  (if  it  exists).  If  no  font 
directory  is  specified,  /usr/lib/fonts/tekfonts  is  used. 

-r  command-line  Run  command-line  to  provide  input  to  the  terminal  emulator.  This  must  be  the  last 
option,  since  the  remainder  of  the  arguments  are  used  by  the  command. 

FILES 

/usr/lib/fonts/tekfonts/tekfont[0-3] 

SEE  ALSO 

shelUool(l),  sunview(l),  kbd(4S),  vfont(5) 

Installing  SunOS  4.1 

BUGS 

Special  point  plot  mode  is  not  supported. 

Z-axis  stuff,  except  for  defocusing,  is  not  supported. 

Defocused  alpha  characters  are  not  supported. 

DIAGNOSTICS 

copy  command  failed  The  copy  command  in  the  TEKCOPY  environment  variable  or  in  the  property 
sheet  could  not  be  executed. 

WARNINGS 

Like  all  4014  emulators,  this  does  not  duplicate  every  nuance  of  the  4014.  For  instance,  certain  programs 
redraw  stuff  already  on  the  screen  in  order  to  highlight  things  with  the  storage  flash.  This  will  not  work 
here.  Also,  even  though  the  emulator  supports  the  full  4096  point  addressing  of  the  4014,  it  cannot  display 
this  on  the  screen.  All  points  will  be  rounded  to  the  nearest  available  pixel.  This  may  cause  some  funny 
effects. 

The  tektool  window  may  be  treated  just  like  other  windows;  it  can  be  overlaid,  moved,  reshaped  etc. 
However,  when  the  window  is  reshaped,  the  contents  will  not  scale. 
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NAME 

telnet  -  user  interface  to  a  remote  system  using  the  TELNET  protocol 
SYNOPSIS 

telnet  [  host  [  port  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

telnet  communicates  widi  another  host  using  the  TELNET  protocol.  If  telnet  is  invoked  without  arguments. 
It  enters  command  mode,  indented  by  its  prompt  (telnet>).  In  this  mode,  it  accepts  and  executes  the  com¬ 
mands  listed  below.  If  it  is  invoked  with  arguments,  it  performs  an  open  command  (see  below)  with  those 
arguments. 

Once  a  connection  has  been  opened,  telnet  enters  input  mode.  In  this  mode,  text  typed  is  sent  to  the 
remote  host.  The  input  mode  entered  will  be  either  “character  at  a  time”  or  “line  by  line”  depending  on 
what  the  remote  system  supports. 

In  ‘‘character  at  a  time”  mode,  most  text  typed  is  immediately  sent  to  the  remote  host  for  processing. 

In  line  by  line  mode,  all  text  is  echoed  locally,  and  (normally)  only  completed  lines  are  sent  to  the  remote 
host.  The  local  echo  character”  (initially  ‘''E’)  may  be  used  to  turn  off  and  on  the  local  echo  (this  would 
mostly  be  used  to  enter  passwords  without  the  password  being  echoed). 

In  either  mode,  if  the  localchars  toggle  is  TRUE  (the  default  in  line  mode;  see  below),  the  user’s  quit,  intr, 
and  flush  characters  are  trapped  locally,  and  sent  as  TELNET  protocol  sequences  to  the  remote  side.  There 
are  options  (see  toggle  autoflush  and  toggle  autosynch  below)  which  cause  this  action  to  flush  subsequent 
output  to  the  terminal  (until  the  remote  host  acknowledges  the  TELNET  sequence)  and  flush  previous  termi¬ 
nal  input  (in  the  case  of  quit  and  intr). 

While  connected  to  a  remote  host,  telnet  command  mode  may  be  entered  by  typing  the  telnet  “escape 
character  (initially  ‘  ]’,  (control-right-bracket)).  When  in  command  mode,  the  normal  terminal  editing 
conventions  are  available. 

USAGE 

Telnet  Commands 

The  following  commands  are  available.  Only  enough  of  each  command  to  uniquely  identify  it  need  be 
typed  (this  is  also  true  for  arguments  to  the  mode,  set,  toggle,  and  display  commands). 

open /zoj/ [  pm  ] 

Open  a  connection  to  the  named  host.  If  no  port  number  is  specified,  telnet  will  attempt  to  contact 
a  TELNET  server  at  the  default  port.  The  host  specification  may  be  either  a  host  name  (see 
hosts(5))  or  an  Internet  address  specified  in  the  “dot  notation”  (see  inet(3N)). 

close  Close  a  TELNET  session  and  return  to  command  mode. 

quit  Close  any  open  TELNET  session  and  exit  telnet.  An  EOF  (in  command  mode)  will  also  close  a 
session  and  exit. 

z  Suspend  telnet.  This  command  only  works  when  the  user  is  using  a  shell  that  supports  job  con¬ 
trol,  such  as  csh(l). 

mode  type 

type  is  either  line  (for  “line  by  line”  mode)  or  character  (for  "character  at  a  time”  mode).  The 
remote  host  is  asked  for  permission  to  go  into  the  requested  mode.  If  the  remote  host  is  capable  of 
entering  that  mode,  the  requested  mode  will  be  entered. 

status  Show  the  current  status  of  telnet.  This  includes  the  peer  one  is  connected  to,  as  well  as  the 
current  mode. 


Sun  Release  4.1 


Last  change:  17  December  1987 


573 


TELNET  (1C) 


USER  COMMANDS 


TELNET  (1C) 


display  [  argument...  ] 

Display  all,  or  some,  of  the  set  and  toggle  values  (see  below). 

?  [  command  ] 

Get  help.  With  no  arguments,  telnet  prints  a  help  summary.  If  a  command  is  specified,  telnet 
will  print  the  help  information  for  just  that  command. 

send  arguments 

Send  one  or  more  special  character  sequences  to  the  remote  host  The  following  are  the  argu¬ 
ments  which  may  be  specified  (more  than  one  argument  may  be  specified  at  a  time): 

escape  Send  the  current  telnet  escape  character  (initially  ’). 

synch  Send  the  TELNET  SYNCH  sequence.  This  sequence  causes  the  remote  system  to  discard 
all  previously  typed  (but  not  yet  read)  input.  This  sequence  is  sent  as  TCP  urgent  data 
(and  may  not  work  if  the  remote  system  is  a  4.2  BSD  system  --  if  it  does  not  work,  a 
lower  case  “r”  may  be  echoed  on  the  terminal). 

brk  Send  the  TELNET  BRK  (Break)  sequence,  which  may  have  significance  to  the  remote 
system. 

ip  Send  the  TELNET  IP  (Interrupt  Process)  sequence,  which  should  cause  the  remote  system 
to  abort  the  currently  running  process. 

ao  Sends  the  TELNET  AO  (Abort  Output)  sequence,  which  should  cause  the  remote  system 
to  flush  all  output  from  the  remote  system  to  the  user’s  terminal. 

ayt  Sends  the  TELNET  AYT  (Are  You  There)  sequence,  to  which  the  remote  system  may  or 
may  not  choose  to  respond. 

ec  Sends  the  TELNET  EC  (Erase  Character)  sequence,  which  should  cause  the  remote  sys¬ 
tem  to  erase  the  last  character  entered. 

el  Sends  the  TELNET  EL  (Erase  Line)  sequence,  which  should  cause  the  remote  system  to 
erase  the  line  currently  being  entered. 

ga  Sends  the  TELNET  GA  (Go  Ahead)  sequence,  which  likely  has  no  significance  to  the 
remote  system. 

nop  Sends  the  TELNET  NOP  (No  Operation)  sequence. 

?  Prints  out  help  information  for  the  send  command, 
set  argument  value 

Set  any  one  of  a  number  of  telnet  variables  to  a  specific  value.  The  special  value  **off  ’  turns  off 
the  function  associated  with  the  variable.  The  values  of  variables  may  be  interrogated  with  the 
display  command.  The  variables  which  may  be  specified  are: 

echo  This  is  the  value  (initially  ‘*E’)  which,  when  in  “line  by  line”  mode,  toggles  between 
doing  local  echoing  of  entered  characters  (for  normal  processing),  and  suppressing  echo¬ 
ing  of  entered  characters  (for  entering,  say,  a  password). 

escape  This  is  the  telnet  escape  character  (initially  **[’)  which  causes  entry  into  telnet  command 
mode  (when  connected  to  a  remote  system). 

interrupt 

If  telnet  is  in  localchars  mode  (see  toggle  localchars  below)  and  the  interrupt  character 
is  typed,  a  TELNET  IP  sequence  (see  send  ip  above)  is  sent  to  the  remote  host.  The  ini¬ 
tial  value  for  the  interrupt  character  is  taken  to  be  the  terminal’s  intr  character. 
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quit  If  telnet  is  in  localchars  mode  (see  toggle  localchars  below)  and  the  quit  character  is 
typed,  a  TELNET  BRK  sequence  (see  send  brk  above)  is  sent  to  the  remote  host.  The  ini¬ 
tial  value  for  the  quit  character  is  taken  to  be  the  terminal’s  quit  character, 

flushoutput 

If  telnet  is  in  localchars  mode  (see  toggle  localchars  below)  and  flushoutput  charac¬ 
ter  is  typed,  a  TELNET  AO  sequence  (see  send  ao  above)  is  sent  to  the  remote  host.  The 
initial  value  for  the  flush  character  is  taken  to  be  the  terminal’s  flush  character. 

erase  If  telnet  is  in  localchars  mode  (see  toggle  localchars  below),  and  if  telnet  is  operating  in 
“character  at  a  time”  mode,  then  when  this  character  is  typed,  a  TELNET  EC  sequence 
(see  send  ec  above)  is  sent  to  the  remote  system.  The  initial  value  for  the  erase  character 
is  taken  to  be  the  terminal’s  erase  character, 

kill  If  telnet  is  in  localchars  mode  (see  toggle  localchars  below),  and  if  telnet  is  operating  in 
“character  at  a  time”  mode,  then  when  this  character  is  typed,  a  TELNET  EL  sequence 
(see  send  el  above)  is  sent  to  the  remote  system.  The  initial  value  for  the  kill  character  is 
taken  to  be  the  terminal’s  kill  character. 

eof  If  telnet  is  operating  in  “line  by  line”  mode,  entering  this  character  as  the  first  character 
on  a  line  will  cause  this  character  to  be  sent  to  the  remote  system.  The  initial  value  of  the 
eof  character  is  taken  to  be  the  terminal’s  eof  character. 

toggle  arguments... 

Toggle  (between  TRUE  and  FALSE)  various  flags  that  control  how  telnet  responds  to  events. 

More  than  one  argument  may  be  specified.  The  state  of  these  flags  may  be  interrogated  with  the 

display  command.  Valid  arguments  are: 

localchars 

If  this  is  TRUE,  then  the  flush,  interrupt,  quit,  erase,  and  kill  characters  (see  set  above) 
are  recognized  locally,  and  transformed  into  (hopefully)  appropriate  TELNET  control 
sequences  (respectively  aojp,  brk,  ec,  and  el;  see  send  above).  The  initial  value  for  this 
toggle  is  TRUE  in  “line  by  line”  mode,  and  FALSE  in  “character  at  a  time”  mode. 

autoflush 

If  autoflush  and  localchars  are  both  TRUE,  then  when  the  ao,  intr,  or  quit  characters  are 
recognized  (and  transformed  into  TELNET  sequences;  see  set  above  for  details),  telnet 
refuses  to  display  any  data  on  the  user’s  terminal  until  the  remote  system  acknowledges 
(via  a  TELNET  Timing  Mark  option)  that  it  has  processed  those  TELNET  sequences.  The 
initial  value  for  this  toggle  is  TRUE  if  the  terminal  user  had  not  done  an  "stty  noflsh",  oth¬ 
erwise  FALSE  (see  stty(lV)). 

autosynch 

If  autosynch  and  localchars  are  both  TRUE,  then  when  either  the  intr  or  quit  characters  is 
typed  (see  set  above  for  descriptions  of  the  intr  and  quit  characters),  the  resulting  TEL¬ 
NET  sequence  sent  is  followed  by  the  TELNET  SYNCH  sequence.  This  procedure  should 
cause  the  remote  system  to  begin  throwing  away  all  previously  typed  input  until  both  of 
the  TELNET  sequences  have  been  read  and  acted  upon.  The  initial  value  of  this  toggle  is 
FALSE. 

crmod  Toggle  RETURN  mode.  When  this  mode  is  enabled,  most  RETURN  characters  received 
from  the  remote  host  will  be  mapped  into  a  RETURN  followed  by  a  LINEFEED.  This 
mode  does  not  affect  those  characters  typed  by  the  user,  only  those  received  from  the 
remote  host.  This  mode  is  not  very  useful  unless  the  remote  host  only  sends  RETURN, 
but  never  LINEFEED.  The  initial  value  for  this  toggle  is  FALSE. 

debug  Toggle  socket  level  debugging  (useful  only  to  the  super-user).  The  initial  value  for  this 
toggle  is  FALSE. 
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options  Toggle  the  display  of  some  internal  telnet  protocol  processing  (having  to  do  with  TEL¬ 
NET  options).  The  initial  value  for  this  toggle  is  FALSE. 

netdata  Toggle  the  display  of  all  network  data  (in  hexadecimal  format).  The  initial  value  for  this 
toggle  is  FALSE. 

?  Display  the  legal  toggle  commands. 

SEE  ALSO 

csh(l),  rlogin(lC),  stty(lV)  inet(3N),  hosts(5) 

BUGS 

There  is  no  adequate  way  for  dealing  with  flow  control. 

On  some  remote  systems,  echo  has  to  be  turned  off  manually  when  in  “line  by  line”  mode. 

There  is  enough  settable  state  to  justify  a  .telnetrc  file. 

No  capability  for  a  .telnetrc  file  is  provided. 

In  “line  by  line”  mode,  the  terminal’s  EOF  character  is  only  recognized  (and  sent  to  the  remote  system) 
when  it  is  the  first  character  on  a  line. 
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NAME 

test  “  return  true  or  false  according  to  a  conditional  expression 

SYNOPSIS 

test  expression 

[  expression  ] 

DESCRIPTION 

test  evaluates  the  expression  expression  and,  if  its  value  is  true,  returns  a  zero  (true)  exit  status;  otherwise, 
a  non-zero  (false)  exit  status  is  returned,  test  returns  a  non-zero  exit  if  there  are  no  arguments. 

USAGE 

Primitives 

The  following  primitives  are  used  to  construct  expression. 

-b  filename 

True  if  filename  exists  and  is  a  block  special  device. 

-c  filename 

True  it  filename  exists  and  is  a  character  special  device, 

-d  filename 

True  if  filename  exists  and  is  a  directory. 

-f  filename 

True  if  filename  exists  and  is  not  a  directory. 
filename 

True  if  filename  exists  and  its  set-group-ID  bit  is  set. 

-h  filename 

True  if  filename  exists  and  is  a  symbolic  link. 

-k  filename 

True  if  filename  exists  and  its  sticky  bit  is  set. 
string  the  length  of  the  string. 

-n  si  True  if  the  length  of  the  string  si  is  non-zero. 

-p  filename 

True  if  filename  exists  and  is  a  named  pipe  (FIFO). 

-r  filename 

True  if  filename  exists  and  is  readable. 

-s  filename 

True  if  filename  exists  and  has  a  size  greater  than  zero. 

-t[fildes] 

True  if  the  open  file  whose  file  descriptor  number  is  fildes  (1  by  default)  is  associated  with  a  ter¬ 
minal  device. 

-u  filename 

True  if  filename  exists  and  its  set-user-ID  bit  is  set. 

-w  filename 

True  if  filename  exists  and  is  writable. 

-X  filename 

True  if  filename  exists  and  is  executable. 
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-z  s2  True  if  the  length  of  string  si  is  zero. 

si  =  s2  True  if  the  strings  si  and  s2  are  equal. 

si  l=s2  True  if  the  strings  si  and  s2  are  not  equal. 

si  True  if  si  is  not  the  null  string. 

nl  -eq  n2  True  if  the  integers  nl  and  n2  are  numerically  equal. 

nl  -ne  h2  True  if  the  integer  nl  is  not  numerically  equal  to  the  integer  n2 . 

nl  -gt  n2  True  if  the  integer  nl  is  numerically  greater  than  the  integer  n2. 

nl  -ge  «2  True  if  the  integer  nl  is  numerically  greater  than  or  equal  to  the  integer  n2 . 

nl  -It  n2  True  if  the  integer  nl  is  numerically  less  than  the  integer  n2 . 

nl  -le  n2  True  if  the  integer  nl  is  numerically  less  than  or  equal  to  the  integer  n2 . 

Operators 

The  above  primaries  may  be  combined  with  the  following  operators: 
t  Unary  negation  operator. 

-a  Binary  and  operator. 

-0  Binary  or  operator. 

(expression) 

Parentheses  for  grouping. 

-a  has  higher  precedence  than  -o.  Notice  that  all  the  operators  and  flags  are  separate  arguments  to  test. 
Notice  also  that  parentheses  are  meaningful  to  the  Shell  and  must  be  escaped. 

SYSTEM  V  USAGE 

The  actions  of  the  System  V  version  of  test  are  the  same,  except  for  the  following  primitives: 

-f  filename  True  if  filename  exists  and  is  a  regular  file. 

-I  string  Not  supported. 

SEE  ALSO 

find(l),  sh(l) 

WARNING 

In  the  second  form  of  the  command  (that  is,  the  one  that  uses  [],  rather  than  the  word  test),  the  square 
brackets  must  be  delimited  by  blanks. 

Some  UNIX  systems  do  not  recognize  the  second  form  of  the  command. 

NOTES 

The  test  command  is  built  into  the  Bourne  shell,  which  chooses  the  4.2  BSD  or  the  System  V  version  of 
test,  depending  on  whether  /usr/5bin  appears  before  /usr/bin  in  the  shell’s  PATH  variable.  This  is  con¬ 
sistent  with  the  behavior  of  other  commands  present  in  both  /usr/bin  and  /usr/5bin. 

The  fact  that  test  is  built  into  the  shell  also  means  that  a  program  named  test  cannot  be  run  without  specify¬ 
ing  a  pathname;  if  the  program  is  in  the  current  directory,  ,/test  will  suffice. 
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NAME 

textedil-  SunView  window-  and  mouse-based  text  editor 
SYNOPSIS 

iexted\t[  generic-tool-arguments]  [-Eaon  |  off]  [ -adjust Jsjjending__delete  ][ -Ei  on  |  off] 

[  -autojndent  ]  [  -Eo  on  |  off  ]  [  -okay__to_overwrite  ]  [  ~Er  on  |  off  ]  [  -read_only  ] 

[  -Ec  N  ]  [  --checkpoint  count  ]  [  -EL  lines  ]  [  -lower_context  lines  ]  [  -Em  pixels  ] 

[  -margin  pixels  ]  [  -En  N  ]  [  -number  of  Jines  lines  ]  [  -Es  N  ]  [  -scratch  window  lines  ] 

[  -ES  N  ]  [  -muiti_click_space  radius  ]  [  -Et  N  ]  [  -tab_width  tabstop  ]  [  -ET  N  ] 

[  -multi-click Jimeout  intrvl  ]  [  -Eu  N  ]  [  -history-limit  max  ]  [  -EU  N  ] 

[  -upper_context  lines  ]  filename 

AVAILABILITY 

This  command  is  available  with  the  SunView  User’s  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.2  for  information  on  how  to  install  optional  software, 

DESCRIPTION 

textedit  is  a  mouse-oriented  text  editor  that  runs  within  the  SunView  environment.  It  creates  a  window 
containing  two  text  subwindows.  The  top  subwindow  (referred  to  as  the  “scratch”  window)  can  hQ  used  to 
store  small  pieces  of  text.  The  bottom  subwindow  (referred  to  as  the  “edit”  window)  displays  the  contents 
of  filename^  if  given. 

The  name  of  the  file  currently  being  edited  is  displayed  in  the  left-hand  portion  of  the  frame  header.  The 
name  of  the  current  working  directory  is  displayed  in  the  right-hand  portion. 

OPTIONS 

generic-tool-arguments 

textedit  accepts  the  SunView  generic  tool  arguments  listed  in  sunview(l). 

-Ea  on  I  off 

-adjust_is_pending_delete 

Choose  whether  or  not  an  adjustment  to  a  selection  makes  the  selection  “pending-delete.” 
TTie  default  is  off.  This  option  corresponds  to,  and  overrides,  the  adjust_iS-p€nding-delete 
Text  defaults  entry. 

-Ei  on  I  off 

-autojndent  Choose  whether  or  not  to  automatically  indent  newly-opened  lines.  The  default  is  off. 
Corresponds  to  the  autojndent  Text  default. 

-Eo  on  I  off 
-okayJo_overwrite 

Set  behavior  to  the  Store  as  New  File  menu  item.  If  on  a  Store  as  New  File  to  the  current 
file  is  treated  as  a  Save  Current  File.  If  off  (the  standard  default),  Store  as  New  File 
operations  using  the  current  filename  result  in  an  error  message.  Corresponds  to 
Storeselfissave. 

-Er  on  I  off 

-read_only  Turn  read-only  mode  on  or  off.  When  on,  text  cannot  be  modified. 

-EcN 

-checkpoint  count 

Checkpoint  after  every  count  editing  operations.  If  count  is  0  (the  standard  default),  no 
checkpointing  takes  place.  Each  character  typed,  each  Paste,  and  each  Cut  counts  as  an 
editing  operation.  Corresponds  to  checkpoint  Jrequency. 
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-EL  lines 

-lower_context  lines 

Specify  the  minimum  number  of  lines  to  keep  between  the  caret  and  the  bottom  of  the  text 
subwindow.  The  default  is  2.  Corresponds  to  lower_context. 

-Em  pixels 
-margin  pixels 

Set  the  scrollbar  margin  width  in  pixels.  The  default  is  4.  Corresponds  to  left__margin. 

~EnN 

-num  hereof Jines  lines 

Set  the  number  of  lines  in  the  bottom  subwindow.  The  default  is  45. 

~EsN 

-scratch^window  lines 

Set  the  number  of  lines  in  the  scratch  window.  A  zero  value  means  that  there  is  no  scratch 
window.  The  standard  default  is  1.  Corresponds  to  scratch_window. 

-ESA^ 

-muUi_click_space  radius 

Set  the  radius,  in  pixels,  within  which  clicks  must  occur  to  be  treated  as  a  multi-click  selec¬ 
tion,  The  default  is  3  pixels.  Corresponds  to  multi_click_space. 

-EtN 

-tab_width  tabstop 

Set  the  number  of  SPACE  characters  displayed  per  TAB  stop.  The  default  is  8.  This  option 
has  no  effect  on  the  characters  in  the  file.  Corresponds  to  tab  width. 

-EIN 

-multiclicktimeout  intrvl 

Set  the  interval,  in  milliseconds,  within  which  any  two  clicks  must  occur  to  be  treated  as  a 
multi-click  selection.  The  default  is  390  milliseconds.  Corresponds  to 
multi_cUck_timeout. 

-EuN 

-historylimit  max 

Set  the  maximum  number  of  editing  operations  that  can  be  undone  or  replayed.  The  default 
is  50.  Corresponds  to  history__limit. 

-EU  N 

-upper_context  lines 

Set  the  minimum  number  of  lines  to  keep  between  the  caret  and  the  top  of  the  text  subwin¬ 
dow.  The  default  is  2.  Corresponds  to  upper_context. 

USAGE 

For  a  description  of  how  to  use  the  facilities  of  the  text  subwindows,  see  the  SunView  User’s  Guide, 

Signal  Processing 

If  textedit  hangs,  for  whatever  reason,  you  can  send  a  SIGHUP  signal  to  its  process  ID,  which  forces  it  to 
write  any  changes  (if  possible): 

kill -HUP  p/ii 

The  edits  are  written  to  the  file  textedit./7id  in  its  working  directory.  If  that  fails,  textedit  successively  tries 
to  write  to  a  file  by  that  name  in  /var/tmp,  and  then  /tmp.  In  addition,  whenever  textedit  catches  a  fatal 
signal,  such  as  SIGILL,  it  tries  to  write  out  the  edits  before  aborting. 
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Defaults  Options 

There  are  ^veral  dozen  user-specified  defaults  that  affect  the  behavior  of  the  text-based  facilities.  See 
deraultsedit(l)  for  a  complete  description.  Important  defaults  entries  in  the  Text  category  are; 

Edit__back_char  Set  the  character  for  erasing  to  the  left  of  the  caret.  The  standard  default  is  DELETE. 

Note:  the  tty  erase  character-setting  has  no  effect  on  textedit.  Text-based  tools  refer 
only  to  the  defaults  database  key  settings. 

Edif_back_word  Set  the  character  for  erasing  the  word  to  the  left  of  the  caret.  The  standard  default  is 
CTRL-W. 

Edit_backjine  Set  the  character  for  erasing  all  characters  to  the  left  of  the  caret.  The  standard 
default  is  CTRL-U. 

Checkpoint__frequency 

If  set  to  0  (the  standard  default)  no  checkpointing  is  done.  For  any  value  greater 
than  zero,  a  checkpoint  is  made  each  time  the  indicated  number  of  editing  operations 
has  been  performed  since  the  last  checkpoint.  Each  character  typed,  each  Paste,  and 
each  Cut  counts  as  an  editing  operation.  The  checkpoint  file  has  a  name  of  the  form: 
filename  %%,  whpre  filename  is  the  name  of  the  file  being  edited. 

Making  a  selection 

In  textedit,  the  mouse  is  used  to  specify  a  selection,  which  is  a  character  span  to  operate  on.  The  mouse  is 
also  used  to  position  the  insertion  point  and  to  invoke  a  menu  of  commands. 

The  assignment  of  commands  to  the  mouse  buttons  is; 

Mouse  button  Description 

left  Starts  a  new  selection  and  moves  the  insertion  point  to  the  end  of  the 

selection  nearest  the  mouse  cursor, 

MIDDLE  Extends  a  selection,  and  moves  the  insertion  point. 

RIGHT  Displays  a  menu  of  operations,  explained  below. 

There  are  two  types  of  selections:  a  primary  selection  is  indicated  by  video-inversion  of  the  span  of  charac¬ 
ters,  and  tends  to  persist.  A  secondary  selection  is  indicated  by  underlining  the  span  of  characters  and  only 
exists  while  one  of  the  four  function  keys  corresponding  to  the  commands  Cut,  Find,  Paste,  or  Copy,  is 
depressed. 

In  addition,  a  selection  can  be  “pending-delete,”  as  indicated  by  overlaying  the  span  of  characters  with  a 
light  gray  pattern.  A  selection  is  made  pending-delete  by  holding  the  CTRL  key  while  clicking  the  LEFT  or 
MIDDLE  mouse  buttons.  If  a  primary  selection  is  pending-delete,  it  is  only  deleted  when  characters  are 
inserted,  either  by  type-in  or  by  Paste  or  Copy.  If  a  secondary  selection  is  pending-delete,  it  is  deleted 
when  the  function  key  is  released,  except  in  the  case  of  the  Find,  which  deselects  the  secondary  selection. 

You  can  make  adjusted  selections  switch  to  pending-delete  using  the  adjust_is_pending_delete  defaults 
entry,  or  the  -Ea  option.  In  this  case,  CTRL-Middle  makes  the  selection  not  pending-delete. 

Commands  that  operate  on  the  primary  selection  do  so  even  if  the  primary  selection  is  not  in  the  window 
that  issued  the  command. 
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Inserting  Text  and  Command  Characters 

For  the  most  part,  typing  any  of  the  standard  keys  either  inserts  the  corresponding  character  at  the  insertion 
point,  or  erases  characters.  However,  certain  key  combinations  are  treated  as  commands.  Some  of  the 
most  useful  are: 

Command  Character  Description 


Cut-Primary  META-X 

Find-Primary  META-F 

Copy-to-Clipboard  META-C 

Paste-Clipboard  META-V 

Copy-then-Paste  META-P 


Go-to-EOF 


CTRL-RETURN 


Erases,  and  moves  to  the  Clipboard,  the  primary  selection. 
Searches  the  text  for  the  pattern  specified  by  the  primary 
selection  or  by  the  Clipboard,  if  there  is  no  primary  selection. 
Copies  the  primary  selection  to  the  Clipboard, 

Inserts  the  Clipboard  contents  at  the  insertion  point. 

Copies  the  primary  selection  to  the  insertion  point  (through 
the  Clipboard). 

Moves  the  insertion  point  to  the  end  of  the  text,  positioning 
the  text  so  that  the  insertion  point  is  visible. 


Function  Keys 

The  commands  indicated  by  use  of  the  function  keys  are: 
Command  Sun-2  ( 3  Key  Description 


Stop 

LI 

Again 

L2 

Undo 

L4 

Front 

L5 

Copy 

L6 

Open 

L7 

Paste 

L8 

Find 

L9 

Cut 

LIO 

CAPSLOCK 

FI 

Aborts  the  current  command. 

Repeats  the  previous  editing  sequence  since  a 
primary  selection  was  made. 

Undoes  a  prior  editing  sequence. 

Makes  the  window  completely  visible  (or 
hides  it,  if  it  is  already  exposed). 

Copies  the  primary  selection,  either  to  the 
Clipboard  or  at  the  closest  end  of  the  secondary 
selection. 

Makes  the  window  iconic  (or  normal,  if  it  is  already 
iconic). 

Copies  either  the  secondary  selection  or  the  Clipboard  at 
the  insertion  point. 

Searches  for  the  pattern  specified  by,  in  order,  the 
secondary  selection,  the  primary  selection,  or  the  Clipboard. 
Erases,  and  moves  to  the  Clipboard,  either  the  primary  or 
the  secondary  selection. 

Forces  all  subsequently  typed  alphabetic  characters 
to  be  upper-case. 

This  key  is  a  toggle;  striking  it  a  second  time  undoes  the 
effect  of  the  first  strike. 


Find  usually  searches  the  text  forwards,  towards  the  end.  Holding  down  the  SHIFT  key  while  invoking 
Find  searches  backward  through  the  text,  towards  the  beginning.  If  the  pattern  is  not  found  before  the 
search  encounters  either  extreme,  it  "wraps  around”  and  continues  from  the  other  extreme.  Find  starts  the 
search  at  the  appropriate  end  of  the  primary  selection,  if  the  primary  selection  is  in  the  subwindow  that  the 
search  is  made  in;  otherwise  it  starts  at  the  insertion  point,  unless  the  subwindow  cannot  be  edited,  in  which 
case  it  starts  at  the  beginning  of  the  text. 

CTRL-Find  invokes  the  Find  and  Replace  pop-up  frame. 

The  default  assignment  of  function  keys  can  be  modified  using  defaultsedit(l). 
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Menu  Items 

File  A  pull-right  menu  item  for  file  operations. 

Edit  A  pull-right  menu  item  equivalent  of  the  editing  function  keys.  The  Edit  submenu  provides 
Again,  Undo.  Copy,  Paste,  and  Cut  (same  as  function  keys  L2.  L4,  L6.  L8,  and  LIO). 

Display  A  pull-right  menu  item  for  controlling  the  way  text  is  displayed  and  line  display  format. 

Find  A  pull-right  menu  item  for  find  and  delimiter  matching  operations. 

Extras  A  user  definable  pull-right  menu  item.  The  Extras  standard  submenu  is  controlled  by 

/usr/lib/text_extras_nienu.  This  file  has  the  same  syntax  as  .rootmenu  file.  See  sun- 
view(l). 

Only  those  items  that  are  active  appear  as  normal  text  in  the  menu;  inactive  items  (which  are  inappropriate 
at  the  time)  are  “grayed  out”. 

User  Defined  Commands 

The  file  /usr/lib/text_extras_menu  specifies  filter  programs  that  are  included  in  the  text  subwindow 
Extras  pull-right  menu  item.  The  file  "Atextswrc  specifies  filter  programs  that  are  assigned  to  (available) 
function  keys.  These  filters  are  applied  to  the  contents  of  the  primary  selection.  Their  output  is  entered  at 
the  caret. 


The  file  /usr/lib/textswrc  is  a  sample  containing  a  set  of  useful  filters.  It  is  not  read  automatically. 
ENVIRONMENT 

The  environment  variables  LC^CTYPE,  LANG,  and  LC_defauIt  control  the  character  classification 
throughout  textedit.  On  entry  to  textedit,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC_defaulL  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  cuirent 
valid  character  classification  rules  of  LC_^CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  “C”  locale. 


FILES 

“/.textswrc 

/  usr/lib/text_extras_m€nu 
/usr/bin 

filename  % 

/tmp/Text+ 


specifies  bindings  of  filters  to  function  keys 

specifies  bindings  of  filters  for  the  extras  menu  pull-right  items 

contains  useful  filters,  including  shift  lines  and  capitalize. 

prior  version  oi  filename  is  available  here  after  a  Save  Current  File  menu 

operation 

edited  version  of  filename;  generated  in  response  to  fatal  internal  errors 
editing  session  logs 


SEE  ALSO 

defaultsedit(l),  kill(l),  sunview(l) 


SunView  User's  Guide 


DIAGNOSTICS 

Cannot  open  file  filename*^  aborting!  filename  does  not  exist  or  cannot  be  read, 
textedit  produces  the  following  exit  status  codes: 

0  normal  termination 

1  standard  SunView  help  message  was  printed 

2  help  message  was  requested  and  printed 

3  abnormal  termination  in  response  to  a  signal,  usually  due  to  an  internal  error 

4  abnormal  termination  during  initialization,  usually  due  to  a  missing  file  or  running  out  of 
swap  space 
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BUGS 

Multi-click  to  change  the  cuirent  selection  does  not  work  for  Adjust  Selection. 
Handling  of  long  lines  is  incorrect  in  certain  scrolling  situations. 

There  is  no  way  to  replay  any  editing  sequence  except  the  most  recent. 
*textedit  newfile*  fails  if  newfile  does  not  exist. 
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NAME 

textedit.filters,  align^equals,  capitalize,  insert_brackets,  remove_brackets,  shift_Iines  -  filters  provided 
with  textedit(l) 

SYNOPSIS 

align_equals 

capitalize  [  -u  I  -1 1  -c  ] 
insert__brackets  I  r 
remove_brackets  I  r 
shift  Jines  [  -t  ]  n 
DESCRIPTION 

Each  of  these  filters  is  designed  to  operate  on  pending-delete  selections  in  text  subwindows.  You  can  use 
them  from  within  text  subwindows  either  by  mapping  them  to  function  keys  in  your  .textswrc  file  or 
adding  them  to  the  text  ‘Extras’  menu  in  your  .text_extras_menu  file.  See  the  SunView  User's  Guide  for 
details.  When  a  filter  is  used  as  a  command  (perhaps  in  a  pipeline),  it  is  applied  to  the  standard  input  and 
the  filtered  text  appears  on  standard  output. 

align_€quals  lines  up  the  *=’  (equ^  signs)  in  C  assignment  statements.  Some  programmers  feel  that  this 
makes  for  improved  readability.  It  aligns  all  equal  signs  with  the  rightmost  equal  sign  in  the  selection  (or 
the  standard  input),  by  padding  with  spaces  between  the  sign  and  the  previous  non  white  character;  it 
replaces  the  selection  with  the  aligned  text  (or  writes  this  text  to  the  standard  output).  For  instance: 
big_long_expression  =  x; 
short erexpr  =  y; 
z  +=  1; 
becomes: 

big_long_expression  =  x; 
short erexpr  =  y; 

z  +=  1; 

capitalize  changes  the  capitalization  of  the  selection  (or  the  standard  input)  and  replaces  it  (or  writes  to  the 
standard  output).  The  -1  option  converts  all  characters  to  lower  case;  -c  converts  the  first  letter  of  each 
word  to  upper  case;  and  -u  converts  all  characters  to  upper  case.  If  no  option  is  specified,  then  capitalize 
consults  its  input  to  determine  what  to  do.  If  the  text  is  all  capitals,  it  is  converted  to  all  lower  case.  If  the 
text  is  all  lower  case  or  of  mixed  cases  and  contains  no  white  space  (such  as  a  NEWLINE,  SPACE,  or  TAB), 
it  is  converted  to  all  capitals.  If  there  is  white  space,  then  the  case  of  the  first  character  in  each  word  is 
inverted. 

insert^brackets  surrounds  the  selection  (or  the  standard  input)  with  the  specified  character  sequences.  I 
and  r  are  the  left-  and  right-bracketing  characters,  respectively. 

remove_brackets  removes  the  left-  and  right-bracketing  characters,  specified  by  I  and  r,  respectively  from 
the  selection  (or  the  standard  input). 

shift_lines  adjusts  indentation  of  the  selection  (or  the  standard  input)  by  n  spaces,  and  replaces  the  selec¬ 
tion  with  the  adjusted  text  (or  writes  to  the  standard  output),  shift  Jines  adjusts  to  the  left  when  n  is  nega¬ 
tive.  If  -t  is  specified,  the  lines  are  shifted  left  or  right  by  n  tab  stops.  The  default  is  8  spaces  per  tab  stop, 
but  if  the  first  line  of  the  selection  (or  the  standard  input)  begins  with  white  space,  then  the  tab  stops  are  set 
to  four  spaces. 


/ 
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FILES 

/tmp/Cap./7irf 

Itmp/lns4)id 

/  usr/lib/.text_extras_menu 
/usr/lib/.textswrc 

SEE  ALSO 

textedit(l) 


temporary  file  used  by  capitalize 
temporary  file  used  by  insert_brackets 
default  ‘Extras’  menu 
sample  function-key  mappings 
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NAME 

tftp  -  trivial  file  transfer  program 

SYNOPSIS 

tftp  [  host  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4,1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

tftp  is  the  user  interface  to  the  Internet  TFTP  (Trivial  File  Transfer  Protocol),  which  allows  users  to  transfer 
files  to  and  from  a  remote  machine.  The  remote  host  may  be  specified  on  the  command  line,  in  which  case 
tftp  uses  host  as  the  default  host  for  future  transfers  (see  the  connect  command  below). 

USAGE 

Commands 

Once  tftp  is  running,  it  issues  the  prompt:  tftp>  and  recognizes  the  following  commands: 
connect  host-name  [  port  ] 

Set  the  host  (and  optionally  port)  for  transfers.  Note;  the  TFTP  protocol,  unlike  the  FTP  protocol, 
does  not  maintain  connections  between  transfers;  thus,  the  connect  command  does  not  actually 
create  a  connection,  but  merely  remembers  what  host  is  to  be  used  for  transfers.  You  do  not  have 
to  use  the  connect  command;  the  remote  host  can  be  specified  as  part  of  the  get  or  put  commands. 

mode  transfer -mode 

Set  the  mode  for  transfers;  transfer-mode  may  be  one  of  ascii  or  binary.  The  default  is  ascii. 

put  filename 

put  localfile  remotefile 

put  filename!  filename2  ..  .filenameN  remote-directory 

Transfer  a  file,  or  a  set  of  files,  to  the  specified  remote  file  or  directory.  The  destination  can  be  in 
one  of  two  forms:  a  filename  on  the  remote  host  if  the  host  has  already  been  specified,  or  a  string 
of  the  form 

hostifilename 

to  specify  both  a  host  and  filename  at  the  same  time.  If  the  latter  form  is  used,  the  specified  host 
becomes  the  default  for  future  transfers.  If  the  remote-directory  form  is  used,  the  remote  host  is 
assumed  to  be  running  the  UNIX  system, 
get  filename 

get  remotename  localname 

get  filenamel  filename2  . . .  JUenameN 

Get  a  file  or  set  of  files  from  the  specified  remote  sources,  source  can  be  in  one  of  two  forms:  a 
filename  on  the  remote  host  if  the  host  has  already  been  specified,  or  a  string  of  die  form 

hostifilename 

to  specify  both  a  host  and  filename  at  the  same  time.  If  the  latter  form  is  used,  the  last  host 
specified  becomes  the  default  for  future  transfers, 

quit  Exit  tftp.  An  EOF  also  exits. 

verbose  Toggle  verbose  mode. 

trace  Toggle  packet  tracing. 

status  Show  current  status. 


Sun  Release  4. 1  Last  change:  26  February  1988  587 


TFTP(IC) 


USER  COMMANDS 


TFTP(IC) 


rexmt  retransmission-timeout 

Set  the  per-packet  retransmission  timeout,  in  seconds. 

timeout  total-transmission-timeout 

Set  the  total  transmission  timeout,  in  seconds. 

ascii  Shorthand  for  mode  ascii. 

binary  Shorthand  for  mode  binary. 

?  [  command-name 

Print  help  infonnation. 

WARNING 

The  default  tran^er-mode  is  ascii.  This  differs  from  pre-4.0  Sun  (and  pre-4.3  BSD)  releases,  so  explicit  ac¬ 
tion  must  now  be  taken  when  transferring  non-AScn  files  such  as  executable  commands. 

BUGS 

Because  there  is  no  user-login  or  validation  within  the  TFTP  protocol,  many  remote  sites  restrict  file  access 
in  various  ways.  Approved  methods  for  file  access  are  specific  to  each  site,  and  therefore  cannot  be  docu¬ 
mented  here. 
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NAME 

time  -  time  a  command 

SYNOPSIS 

time  [  command  ] 

SYSTEM  V  SYNOPSIS 

/usr/5bin/time  [  command  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

There  are  three  distinct  versions  of  time:  it  is  built  in  to  the  C  shell,  and  is  an  executable  program  available 
in  /usr/bin/time  and  /usr/5bin/time  when  using  the  Bourne  shell.  In  each  case,  times  are  displayed  on  the 
diagnostic  output  stream. 

In  the  case  of  the  C  shell,  a  time  command  with  no  command  argument  simply  displays  a  summary  of  time 
used  by  this  shell  and  its  children.  When  arguments  are  given  the  specified  simple  command  is  timed  and 
the  C  shell  displays  a  time  summary  as  described  in  csh(l). 

The  time  commands  in  /usr/bin/time  and  /usr/5bin/time  time  the  given  command,  which  must  be 
specified,  that  is,  command  is  not  optional  as  it  is  in  the  C  shell’s  timing  facility.  When  the  command  is 
complete,  time  displays  the  elapsed  time  during  the  command,  the  time  spent  in  the  system,  and  the  time 
spent  in  execution  of  the  command.  Times  are  reported  in  seconds.  The  only  difference  between  the  ver¬ 
sions  in  /usr/bin/time  and  /usr/5bin/time  is  between  their  output  formats;  /usr/bin/time  prints  all  three 
times  on  the  same  line,  while  /usr/5bin/time  prints  them  on  separate  lines. 

EXAMPLES 

The  three  examples  here  show  the  differences  between  the  csh  version  of  time  and  the  versions  in 
/usr/bin/time  and  /usr/bin/time.  The  example  assumes  that  csh  is  the  shell  in  use. 

example%  time  wc  /usr/share/man/manl/csh.l 

1876  11223  65895  /usr/share/man/manl/csh.l 

2.7u  0.9s  0:03  91%  3+5k  19+2io  Ipf+Ow 

example %/usr/bin/time  wc  /usr/share/man/manl/csh.l 

1876  11223  65895 /usr/share/man/manl/csh.l 

4.3  real  2.7  user  1.0  sys 

example%  /usr/5bin/time  wc  /usr/share/man/manl/csh.l 

1876  11223  65895 /usr/share/man/manl/csh.l 

real  4,3 

user  2.7 

sys  1,0 

example% 

SEE  ALSO 

csh(l) 
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BUGS 

Elapsed  time  is  accurate  to  the  second,  while  the  CPU  times  are  measured  to  the  50th  second.  Thus  the  sum 
of  the  CPU  times  can  be  up  to  a  second  larger  than  the  elapsed  time. 

When  the  command  being  limed  is  interrupted,  the  timing  values  displayed  may  not  always  be  accurate. 
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NAME 

tip  -  connect  to  remote  system 
SYNOPSIS 

tip  [  -V  ]  [  -speed-entry  ]  hostname  I  phone-number 
DESCRIPTION 

tip  establishes  a  full-duplex  terminal  connection  to  a  remote  host.  Once  the  connection  is  established,  a 
remote  session  using  tip  behaves  like  an  interactive  session  on  a  local  terminal. 

The  remote  file  (described  in  the  remote(5)  manual  page)  contains  entries  describing  remote  systems  and 
line  speeds  used  by  tip. 

Each  host  has  a  default  baud  rate  for  the  connection,  or  you  can  specify  a  speed  with  the  -speed-entry 
command  line  argument. 

When  phone-number  is  specified,  tip  looks  for  an  entry  in  the  remote  file  of  the  form: 
tip  -speed-entry 

When  it  finds  such  an  entry,  it  sets  the  connection  speed  accordingly.  If  it  finds  no  such  entry,  tip  interprets 
-speed-entry  as  if  it  were  a  system  name,  resulting  in  an  error  message. 

If  you  omit  -speed-entry,  tip  uses  the  tipO  entry  to  set  a  speed  for  the  connection. 

When  establishing  the  connection  tip  sends  a  connection  message  to  the  remote  system.  The  default  value 
for  this  message  can  be  found  in  the  remote  file. 

When  tip  attempts  to  connect  to  a  remote  system,  it  opens  the  associated  device  with  an  exclusive-open 
ioctl(2)  call.  Thus  only  one  user  at  a  time  may  access  a  device.  This  is  to  prevent  multiple  processes  from 
sampling  the  terminal  line.  In  addition,  tip  honors  the  locking  protocol  used  by  uucp(lC). 

When  tip  starts  up  it  reads  commands  from  the  file  .tiprc  in  your  home  directory. 

OPTIONS 

-v  Display  commands  from  the  .tiprc  file  as  they  are  executed. 

USAGE 

Typed  characters  are  normally  transmitted  directly  to  the  remote  machine  (which  does  the  echoing  as  well). 

At  any  time  that  tip  prompts  for  an  argument  (for  example,  during  setup  of  a  file  transfer)  the  line  typed 
may  be  edited  with  the  standard  erase  and  kill  characters.  A  null  line  in  response  to  a  prompt,  or  an  inter¬ 
rupt,  aborts  the  dialogue  and  returns  you  to  the  remote  machine. 

Commands 

A  tilde  (  )  appearing  as  the  first  character  of  a  line  is  an  escape  signal  which  directs  tip  to  perform  some 
special  action,  tip  recognizes  the  following  escape  sequences: 

'"D 

Drop  the  connection  and  exit  (you  may  still  be  logged  in  on  the  remote  machine). 

~c  [name] 

Change  directory  to  name  (no  argument  implies  change  to  your  home  directory). 

“!  Escape  to  an  interactive  shell  on  the  local  machine  (exiting  the  shell  returns  you  to  tip). 

“>  Copy  file  from  local  to  remote. 

"<  Copy  file  from  remote  to  local. 
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"p  from  [  to  ] 

Send  a  file  to  a  remote  host  running  the  UNIX  system.  When  you  use  the  put  command,  the 
remote  system  runs  the  command  string 

cat  >  to 

while  tip  sends  it  the  from  file.  If  the  to  file  is  not  specified,  the  from  file  name  is  used.  This  com¬ 
mand  is  actually  a  UNIX-system-specific  version  of  the  command. 

‘t  from  [  to  ] 

Take  a  file  from  a  remote  host  running  the  UNIX  system.  As  in  the  put  command  the  to  file 
defaults  to  the  from  file  name  if  it  is  not  specified.  The  remote  host  executes  the  command  string 

cat  from  ;  echo  *A 

to  send  the  file  to  tip. 

“I  Pipe  the  output  from  a  remote  command  to  a  local  process.  The  command  string  sent  to  the  local 
system  is  processed  by  the  shell. 

“C  Connect  a  program  to  the  remote  machine.  The  command  string  sent  to  the  program  is  processed 
by  the  shell.  The  program  inherits  file  descriptors  0  as  remote  line  input,  1  as  remote  line  output, 
and  2  as  tty  standard  error. 

“$  Pipe  the  output  from  a  local  process  to  the  remote  host.  The  command  siring  sent  to  the  local  sys¬ 
tem  is  processed  by  the  shell. 

“#  Send  a  BREAK  to  the  remote  system. 

"s  Set  a  variable  (see  the  discussion  below). 

""Z  Stop  tip  (only  available  when  run  under  a  shell  that  supports  job  control,  such  as  the  C  shell). 

Stop  only  the  “local  side”  of  tip  (only  available  when  run  under  a  shell  that  supports  job  control, 
such  as  the  C  shell);  the  “remote  side”  of  tip,  the  side  that  displays  output  from  the  remote  host,  is 
left  running. 

"?  Get  a  summary  of  the  tilde  escapes. 

Copying  files  requires  some  cooperation  on  the  part  of  the  remote  host.  When  a  or  "<  escape  is  used  to 
send  a  file,  tip  prompts  for  a  file  name  (to  be  transmitted  or  received)  and  a  command  to  be  sent  to  the 
remote  system,  in  case  the  file  is  being  transferred  from  the  remote  system.  The  default  end  of  transmis¬ 
sion  string  for  transferring  a  file  from  the  local  system  to  the  remote  is  specified  as  the  oe  capability  in  the 
remote (5)  file,  but  may  be  changed  by  the  set  command.  While  tip  is  transferring  a  file  the  number  of 
lines  transferred  will  be  continuously  displayed  on  the  screen.  A  file  transfer  may  be  aborted  with  an  inter¬ 
rupt. 

AUTO-CALL  UNITS 

tip  may  be  used  to  dial  up  remote  systems  using  a  number  of  auto-call  unit’s  (ACU’s).  When  the  remote 
system  description  contains  the  du  capability,  tip  uses  the  call-unit  (cu),  ACU  type  (at),  and  phone  numbers 
(pn)  supplied.  Normally  tip  displays  verbose  messages  as  it  dials.  See  remote(5)  for  details  of  the  remote 
host  specification. 

Depending  on  the  type  of  auto-dialer  being  used  to  establish  a  connection  the  remote  host  may  have  gar¬ 
bage  characters  sent  to  it  upon  connection.  The  user  should  never  assume  that  the  first  characters  typed  to 
the  foreign  host  are  the  first  ones  presented  to  it.  The  recommended  practice  is  to  immediately  type  a  kill 
character  upon  establishing  a  connection  (most  UNIX  systems  either  support  @  or  CTRL-U  as  the  initial  kill 
character). 

tip  currently  supports  the  Ventel  MD-212+  modem  and  DC  Hayes-compatible  modems. 
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REMOTE  HOST  DESCRIPTIONS 

Descriptions  of  remote  hosts  are  normally  located  in  the  system-wide  file  /etc/remote.  However,  a  user 
may  maintain  personal  description  files  (and  phone  numbers)  by  defining  and  exporting  the  REMOTE  shell 
variable.  The  remote  file  must  be  readable  by  tip,  but  a  secondary  file  describing  phone  numbers  may  be 
mamtained  readable  only  by  the  user.  This  secondary  phone  number  file  is  /etc/phones,  unless  the  shell 
variable  PHONES  is  defined  and  exported.  As  described  in  remote(5),  the  phones  file  is  read  when  the  host 
description  s  phone  number(s)  capability  is  an  The  phone  number  file  contains  lines  of  the  form; 

system-name  phone-number 

Each  phone  number  found  for  a  system  is  tried  until  either  a  connection  is  established,  or  an  end  of  file  is 
reached.  Phone  numbers  are  constructed  from  ‘0123456789-=*’,  where  the  ‘=’  and  **’  are  used  to  indi¬ 
cate  a  second  dial  tone  should  be  waited  for  (ACU  dependent). 

TIP  INTERNAL  VARIABLES 

tip  maintains  a  set  of  variables  which  are  used  in  normal  operation.  Some  of  these  variables  are  read-only 
to  normal  users  (root  is  allowed  to  change  anything  of  interest).  Variables  may  be  displayed  and  set 
through  the  “s  e^ape.  The  syntax  for  variables  is  patterned  after  vi(l)  and  mail(l).  Supplying  all  as  an 
argument  to  the  s  escape  displays  all  variables  that  the  user  can  read.  Alternatively,  the  user  may  request 
display  of  a  particular  variable  by  attaching  a  ?  to  the  end.  For  example  ‘~s  escape?’  displays  the  current 
escape  character. 

Variables  are  numeric,  string,  character,  or  Boolean  values.  Boolean  variables  are  set  merely  by  specifying 
their  name.  They  may  be  reset  by  prepending  a  !  to  the  name.  Other  variable  types  are  set  by  appending 
an  =  and  the  value.  The  entire  assignment  must  not  have  any  blanks  in  it.  A  single  set  command  may  be 
used  to  interrogate  as  well  as  set  a  number  of  variables. 

Variables  may  be  initialized  at  run  time  by  placing  set  commands  (without  the  "s  prefix)  in  a  .tiprc  file  in 
one’s  home  directory.  The  -v  option  makes  tip  display  the  sets  as  they  are  made.  Comments  preceded  by 
a  #  sign  can  appear  in  the  .tiprc  file. 

Finely,  the  variable  names  must  either  be  completely  specified  or  an  abbreviation  may  be  given.  The  fol¬ 
lowing  list  details  those  variables  known  to  tip. 

beautify 

(bool)  Discard  unprintable  characters  when  a  session  is  being  scripted;  abbreviated  be.  If  the  nb 
capability  is  present,  beautify  is  initially  set  to  otherwise,  beautify  is  initially  set  to  o/i. 

baudrate 

(num)  The  baud  rate  at  which  the  connection  was  established;  abbreviated  ba.  If  a  baud  rate  was 
specified  on  the  command  line,  baudrate  is  initially  set  to  the  specified  value;  otherwise,  if  the  br 
capability  is  present,  baudrate  is  initially  set  to  the  value  of  that  capability;  otherwise,  baudrate 
is  set  to  300  baud.  Once  tip  has  been  started,  baudrate  can  only  changed  by  the  super-user. 

dialtimeout 

(num)  When  dialing  a  phone  number,  the  time  (in  seconds)  to  wait  for  a  connection  to  be  esta¬ 
blished;  abbreviated  dial,  dialtimeout  is  initially  set  to  60  seconds,  and  can  only  changed  by  the 
super-user. 

disconnect 

(str)  The  string  to  send  to  the  remote  host  to  disconnect  from  it;  abbreviated  di.  If  the  di  capability 
is  present,  disconnect  is  initially  set  to  the  value  of  that  capability;  otherwise,  disconnect  is  set  to 
a  null  string  (””). 

echocheck 

(bool)  Synchronize  with  the  remote  host  during  file  transfer  by  waiting  for  the  echo  of  the  last 
character  transmitted;  abbreviated  ec.  If  the  ec  capability  is  present,  echocheck  is  initially  set  to 
on;  otherwise,  echocheck  is  initially  set  to  off. 
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eofread  (str)  The  set  of  characters  which  signify  an  end-of-transmission  during  a  ’“<  file  transfer  command; 
abbreviated  eofr.  If  the  ie  capability  is  present,  eofread  is  initially  set  to  the  value  of  that  capabil¬ 
ity;  otherwise,  eofread  is  set  to  a  null  string 

eofwrite 

(str)  The  string  sent  to  indicate  end-of-transmission  during  a  ”>  file  transfer  command;  abbreviated 
eofw.  If  the  oe  capability  is  present,  eofread  is  initially  set  to  the  value  of  that  capability;  other¬ 
wise,  eofread  is  set  to  a  null  string 

eol  (str)  The  set  of  characters  which  indicate  an  end-of-line.  tip  will  recognize  escape  characters  only 
after  an  end-of-line.  If  the  el  capability  is  present,  eol  is  initially  set  to  the  value  of  that  capability; 
otherwise,  eol  is  set  to  a  null  string 

escape  (char)  The  command  prefix  (escape)  character;  abbreviated  es.  If  the  es  capability  is  present, 
escape  is  initially  set  to  the  value  of  that  capability;  otherwise,  escape  is  set  to  * ' 

etimeout 

(num)  The  amount  of  time,  in  seconds,  that  tip  should  wait  for  the  echo-check  response  when 
echocheck  is  set;  abbreviated  et.  If  the  et  capability  is  present,  etimeout  is  initially  set  to  the 
value  of  that  capability;  otherwise,  etimeout  is  set  to  10  seconds. 

exceptions 

(str)  The  set  of  characters  which  should  not  be  discarded  due  to  the  beautification  switch;  abbrevi¬ 
ated  ex.  If  the  ex  capability  is  present,  exceptions  is  initially  set  to  the  value  of  that  capability; 
otherwise,  exceptions  is  set  to  *\t\n\f\b’. 

force  (char)  The  character  used  to  force  literal  data  transmission;  abbreviated  fo.  If  the  fo  capability  is 
present,  force  is  initially  set  to  the  value  of  that  capability;  otherwise,  force  is  set  to  \377  (which 
disables  it). 

frames  ize 

(num)  The  amount  of  data  (in  bytes)  to  buffer  between  file  system  writes  when  receiving  files; 
abbreviated  fr.  If  the  fs  capability  is  present,  framesize  is  initially  set  to  the  value  of  that  capabil¬ 
ity;  otherwise,  framesize  is  set  to  1024. 

halfduplex 

(bool)  Do  local  echoing  because  the  host  is  half-duplex;  abbreviated  hdx.  If  the  hd  capability  is 
present,  halfduplex  is  initially  set  to  on;  otherwise,  halfduplex  is  initially  set  to  off. 

hardwareflow 

(bool)  Do  hardware  flow  control;  abbreviated  hf.  If  the  hf  capability  is  present,  hardwareflow  is 
initially  set  to  on;  otherwise,  hardwareflowcontrol  is  initially  set  to  off. 

host  (str)  The  name  of  the  host  to  which  you  are  connected;  abbreviated  ho.  host  is  permanendy  set  to 
the  name  given  on  the  command  line  or  in  the  HOST  environment  variable. 

localecho 

(bool)  A  synonym  for  halfduplex;  abbreviated  le. 

log  (str)  The  name  of  the  file  to  which  to  log  information  about  outgoing  phone  calls.  log  is  initially 
set  to  /var/adm/aculog,  and  can  only  be  inspected  or  changed  by  the  super-user. 

parity  (str)  The  parity  to  be  generated  and  checked  when  talking  to  the  remote  host;  abbreviated  par. 
The  possible  values  are: 

none 

zero  Parity  is  not  checked  on  input,  and  the  parity  bit  is  set  to  zero  on  output, 
one  Parity  is  not  checked  on  input,  and  the  parity  bit  is  set  to  one  on  output. 
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( 

t  : 


even  Even  parity  is  checked  for  on  input  and  generated  on  output. 

odd  Odd  parity  is  checked  for  on  input  and  generated  on  output. 

If  the  pa  capability  is  present,  parity  is  initially  set  to  the  value  of  that  capability  ;  otherwise,  par¬ 
ity  is  set  to  none. 

phones  The  file  in  which  to  find  hidden  phone  numbers.  If  the  environment  variable  PHONES  is  set, 
phones  is  set  to  the  value  of  PHONES;  otherwise,  phones  is  set  to  /etc/phones.  The  value  of 
phones  cannot  be  changed  from  within  tip. 

prompt  (char)  The  character  which  indicates  an  end-of-line  on  the  remote  host;  abbreviated  pr.  This 
value  is  used  to  synchronize  during  data  transfers.  The  count  of  lines  transferred  during  a  file 
transfer  command  is  based  on  receipt  of  this  character.  If  the  pr  capability  is  present,  prompt  is 
initially  set  to  the  value  of  that  capability;  otherwise,  prompt  is  set  to  \n. 

raise  (bool)  Upper  case  mapping  mode;  abbreviated  ra.  When  this  mode  is  enabled,  all  lower  case 
letters  will  be  mapped  to  upper  case  by  tip  for  transmission  to  the  remote  machine.  If  the  ra  capa¬ 
bility  is  present,  raise  is  initially  set  to  on\  otherwise,  raise  is  initially  set  to  off. 

raisechar 

(char)  The  input  character  used  to  toggle  upper  case  mapping  mode;  abbreviated  rc.  If  the  rc 
capability  is  present,  raisechar  is  initially  set  to  the  value  of  that  capability;  otherwise,  raisechar 
is  set  to  ^11  (which  disables  it). 

rawftp  (bool)  Send  all  characters  during  file  transfers;  do  not  filter  non-printable  characters,  and  do  not  do 
translations  like  \n  to  \r.  Abbreviated  raw.  If  the  rw  capability  is  present,  rawftp  is  initially  set 
to  on\  otherwise,  rawftp  is  initially  set  to  off. 

record  (str)  The  name  of  the  file  in  which  a  session  script  is  recorded;  abbreviated  rec.  If  the  re  capabil¬ 
ity  is  present,  record  is  initially  set  to  the  value  of  that  capability;  otherwise,  record  is  set  to 
tip.record. 

remote  The  file  in  which  to  find  descriptions  of  remote  systems.  If  the  environment  variable  REMOTE  is 
set,  remote  is  set  to  the  value  of  REMOTE;  otherwise,  remote  is  set  to  /etc/remote.  The  value  of 
remote  cannot  be  changed  from  within  tip. 

script  (bool)  Session  scripting  mode;  abbreviated  sc.  When  script  is  on,  tip  will  record  everything 
transmitted  by  the  remote  machine  in  the  script  record  file  specified  in  record.  If  the  beautify 
switch  is  on,  only  printable  ASCII  characters  will  be  included  in  the  script  file  (those  characters 
between  040  and  0177).  The  variable  exceptions  is  used  to  indicate  characters  which  are  an 
exception  to  the  normal  beautification  rules.  If  the  sc  capability  is  present,  script  is  initially  set  to 
on',  otherwise,  script  is  initially  set  to  off. 

tabexpand 

(bool)  Expand  TAB  characters  to  SPACE  characters  during  file  transfers;  abbreviated  tab.  When 
tabexpand  is  on,  each  tab  is  expanded  to  8  SPACE  characters.  If  the  tb  capability  is  present, 
tabexpand  is  initially  set  to  on',  otherwise,  tabexpand  is  initially  set  to  off. 

tandem  (bool)  Use  XON/XOFF  flow  control  to  limit  the  rate  that  data  is  sent  by  the  remote  host;  abbrevi¬ 
ated  ta.  If  the  nt  capability  is  present,  tandem  is  initially  set  to  off',  otherwise,  tandem  is  initially 
settoort. 

verbose  (bool)  Verbose  mode;  abbreviated  verb;  When  verbose  mode  is  enabled,  tip  prints  messages 
while  dialing,  shows  the  current  number  of  lines  transferred  during  a  file  transfer  operations,  and 
more.  If  the  nv  capability  is  present,  verbose  is  initially  set  to  off’,  otherwise,  verbose  is  initially 
settoort. 

SHELL  (str)  The  name  of  the  shell  to  use  for  the  "t  command;  default  value  is  /bin/sh,  or  taken  from  the 
environment. 

HOME  (str)  The  home  directory  to  use  for  the  “c  command;  default  value  is  taken  from  the  environment. 
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EXAMPLES 

An  example  of  the  dialogue  used  to  transfer  files  is  given  below. 
arpa%  tip  monet 
[connected] 

. .  .(assume  we  are  talking  to  a  UNIX  system). . . 

ucbmonet  login:  sam 
Password: 

monet  %  cat  >  sylvester.c 
">  Filename:  Sylvester  .c 
32  lines  transferred  in  1  minute  3  seconds 
monet  % 

monet  %  '<  Filename:  reply.c 
List  command  for  remote  host:  cat  reply.c 
65  lines  transferred  in  2  minutes 
monet  % 

. .  .(or,  equivalently). . . 

monet  %  "p  sylvester.c 

. .  .(actually  echoes  as  “{put]  sylvester.c). . . 

32  lines  transferred  in  1  minute  3  seconds 
monet  % 

monet  %  "t  reply.c 

. .  .(actually  echoes  as  "[take]  reply.c). . . 

65  lines  transferred  in  2  minutes 
monet  % 

...(to  print  a  file  locally). . . 

monet  %  "ILocal  command:  pr  -h  sylvester.c  |  Ipr 
List  command  for  remote  host;  cat  sylvester.c 
monet  %  ""D 
[EOT] 

. .  .(back  on  the  local  system). , . 


ENVIRONMENT 

The  following  environment  variables  are  read  by  tip. 

REMOTE  The  location  of  the  remote  file. 

PHONES  The  location  of  the  file  containing  private  phone  numbers. 
HOST  A  default  host  to  connect  to. 

HOME  One’s  log-in  directory  (for  chdirs). 

SHELL  The  shell  to  fork  on  a*"!’  escape. 

FILES 

"Z.tiprc  initialization  file 

/var/spool/locks/LCK  .  .♦  lock  file  to  avoid  conflicts  with  UUCP 
/var/adm/aculog  file  in  which  outgoing  calls  are  logged 

/etc/phones 
/etc/remote 


■\ 
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SEE  ALSO 

cu(lC),  inail(l),  uucp(lC),  vi(l),  ioctl(2),  phones(5),  reinote(5) 

BUGS 

There  are  two  additional  variables  chardelay  and  linedelay  that  are  currently  not  implemented. 
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NAME 

toolplaces  -  display  current  SunView  window  locations,  sizes,  and  other  attributes 
SYNOPSIS 

toolplaces  [  -oIO|u  ]  [  -help  ] 

AVAILABILITY 

This  command  is  available  with  the  SunView  User's  Guide  software  installation  option.  Refer  to  Installing 
SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

toolplaces  generates  position,  size,  label,  and  program  attributes  for  the  windows  running  on  a  SunView 
screen  at  the  time  of  execution,  (toolplaces  does  not  work  when  SunView  is  not  running.) 

Many  people  redirect  standard  output  from  toolplaces  to  the  .sunview  file,  so  as  to  reuse  the  current  win¬ 
dow  system  attributes  each  time  they  execute  sunview(l). 

For  each  window  on  the  screen  at  execution  time,  toolplaces  shows: 

the  tool  name 

the  “open”  window  position 
the  size  of  the  window  in  pixels 
the  “closed,”  or  icon,  window  position 
an  indicator  of  whether  the  window  is  open  or  closed 
the  label  at  the  top  of  the  window 
the  name  of  the  program  running  in  the  window,  if  a 
program  is  running  there 

any  flags  or  options  to  a  program  running  in  the  window 

toolplaces  describes  each  window  on  one  output  line,  as  long  as  necessary,  using  the  current  sunview  for¬ 
mat. 

Current  sunview  format  consists  of  window  tool  descriptions,  one  per  line,  as  in  this  example  (the  \  indi¬ 
cates  that  the  current  line  continues  on  the  next  line): 

shelltool  -Wp  491  795  -Ws  580  87  -WP  0  836  -C 
clock  -Wp  120  120  -Ws  122  55  -WP  1086  826  -Wl  \ 

~W1 "  open  clock"  -S  -r  -d  wdm 
shelltool  -Wp  491 166 -Ws  650  567 -WP  702  836  \ 

-Wl  due  rlogin  due 

shelltool  -Wp  0  0  -Ws  650  525  -WP  64  836  \ 

-Wl  "Small  Window:  /usr/bin/csh" 
shelltool  -Wp  501  0 -Ws  650  812 -WP  128  836  \ 

-Wl  "Big  Window:  /usr/bin/csh” 

OPTIONS 

-0  Show  window  tool  information  in  the  old  suntools  format  for  window  attributes,  but  specifies  the 
appropriate  tool  names  for  each  tool. 

-O  Show  window  tool  information  in  the  old  suntools  format  for  window  attributes,  specifying  tool- 
name  as  the  name  for  each  tool. 

-u  Show  the  updated  window  tool  information  in  the  order  that  you  originally  specified  it. 

-help  Show  help  information  preceding  tool  attributes. 
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FILES 

"/.sunview 

SEE  ALSO 

sunview(l) 

SunView  User’s  Guide 


format  file  for  sunview(l) 
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NAME 

touch  -  update  the  access  and  modification  times  of  a  file 
SYNOPSIS 

touch  [  -c  ]  [  -f  ]  filename, . . 

SYSTEM  V  SYNOPSIS 

/usr/Sbin/touch  [  -acm  ]  [  date-time  ]  filename,. . 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

touch  sets  the  access  and  modification  times  of  each  argument  to  the  current  time.  A  file  is  created  if  it 
does  not  already  exist. 

touch  is  valuable  when  used  in  conjunction  with  make(l),  where,  for  instance,  you  might  want  to  force  a 
complete  rebuild  of  a  program  composed  of  many  pieces.  In  such  a  case,  you  might  type: 

exaTnple%  touch  +.c 
example  %  make 

make(l)  would  then  see  that  all  the  .c  files  were  more  recent  than  the  corresponding  .o  files,  and  would 
start  the  compilation  from  scratch. 

OPTIONS 

“C  Do  not  create  filename  if  it  does  not  exist. 

-f  Attempt  to  force  the  touch  in  spite  of  read  and  write  permissions  on  filename . 

SYSTEM  V  OPTIONS 

Options  must  be  grouped  to  form  the  first  argument.  The  date-time  argument  takes  the  form: 
mmddhhmm\yy^ 

and  updates  the  modification  time  to  that  specified,  rather  than  the  current  time.  The  first  mm  is  the  month, 
dd  is  the  day  of  the  month,  hh  is  the  hour,  and  the  second  mm  is  the  minute.  If  yy  is  specified,  it  is  the  last 
two  digits  of  the  year.  If  omitted,  the  current  year  is  assumed. 

-a  Update  only  the  access  time. 

-c  Do  not  create  filename  if  it  does  not  exist. 

-m  Update  only  the  modification  time. 

SEE  ALSO 

make(l),  utimes(2) 

BUGS 

It  is  difficult  to  touch  a  file  whose  name  consists  entirely  of  digits  in  the  System  V  touch,  as  it  will  interpret 
the  first  such  non-flag  argument  as  a  time.  You  must  ensure  that  there  is  a  character  in  the  name  which  is 
not  a  digit,  by  specifying  it  as  Jname  rather  than  name. 
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NAME 

tput  -  initialize  a  terminal  or  query  the  terminfo  database 
SYNOPSIS 

/usr/5bin/tput  [  -Ttype  ]  capability  [  parameter  . . .  ] 

/usr/Sbin/tput  [  -Ttype  ]  init 
/usr/Sbin/tput  [  —Ttype  ]  longname 
/usr/5bin/tput  [  —Ttype  ]  reset 
AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

tput  uses  the  terminfo(5V)  database  to  make  the  values  of  terminal-dependent  capabilities  and  information 
available  to  the  shell,  to  initialize  or  reset  the  terminal,  or  return  the  long  name  of  the  requested  terminal 
type.  Normally,  the  terminal  type  is  taken  from  the  environment  variable  TERM;  if  the  -Ttype  option  is 
specified,  the  terminal  type  is  taken  from  that  option. 

tput  displays  a  string  if  the  given  capability  is  a  string  capability,  or  an  integer  if  it  is  an  integer  capability; 
it  displays  no  output  if  the  capability  is  a  boolean. 

If  capability  is  a  boolean,  tput  returns  tme  (0)  if  that  capability  is  set,  or  false  (1)  otherwise.  If  capability 
is  a  string,  tput  returns  true  (0)  if  that  capability  is  set,  or  false  (1)  otherwise.  If  capability  is  an  integer,  a 
value  of  true  (0)  is  returned  whether  or  not  the  capability  is  set  for  the  terminal.  To  determine  if  an  integer 
capability  is  set,  you  must  examine  the  standard  outpuL 

For  a  complete  list  of  capabilities  and  the  capability  associated  with  each,  see  terminfo(5V). 

If  capability  is  a  string  capability  that  takes  parameters,  the  parameter  arguments  are  instantiated  into  the 
string.  An  all-numeric  parameter  argument  is  passed  to  the  attribute  as  a  number. 

OPTIONS 

-Ttype  Indicate  the  type  of  terminal.  If  this  option  is  supplied,  the  environment  variables  LINES  and 
COLUMNS  are  not  used, 

init  If  the  terminfo  database  is  present  and  an  entry  for  the  user’s  terminal  exists,  emit  the  terminal’s 
initialization  strings,  set  up  any  delays  specified,  and  turn  the  expansion  of  TAB  characters  on  or 
off,  as  specified  by  the  terminal’s  entry  in  the  terminfo  database.  If  the  terminal  has  a  TAB  char¬ 
acter,  and  either  has  a  capability  for  setting  TAB  characters  or  initially  has  its  TAB  characters  set 
every  8  SPACE  characters,  expansion  of  TAB  characters  is  turned  off,  otherwise  expansion  of  TAB 
characters  is  turned  on.  If  expansion  of  TAB  characters  is  turned  on,  and  the  terminal  has  a  capa¬ 
bility  for  setting  TAB  characters,  TAB  stops  are  set  to  every  eight  columns.  If  an  entry  does  not 
contain  the  information  needed  for  any  of  these  actions,  that  action  is  silently  skipped. 

reset  Emit  the  terminal’s  reset  strings,  and  set  up  delays  and  TAB  characters  as  specified.  If  the  reset 
strings  are  not  present,  but  initialization  strings  are,  the  initialization  strings  are  used. 

longname 

If  the  terminfo  database  is  present  and  an  entry  for  the  user’s  terminal  exists,  emit  the  long  name 
of  the  terminal.  The  long  name  is  the  last  name  in  the  first  line  of  the  terminal’s  description  in  the 
terminfo  database. 
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EXIT  CODES 

0  The  boolean  or  string  capability  is  set,  or  the  capability  is  an  integer  type  and  is  present. 

1  The  capability  is  not  set. 

2  Usage  eiror. 

3  The  terminal  is  of  an  unknown  type,  or  the  terminfo  database  is  not  present 

4  Unknown  terminfo  capability. 

-1  The  integer  capability  is  not  defined  for  this  terminal  type. 

EXAMPLES 


tput  init 

tput  -Tsun  reset 

tput  cup  0  0 

tput  clear 
tput  cols 
tput  -Tsun  cols 
bold=‘tput  smso‘ 
offbold=Uput  rmso‘ 


tput  he 
tput  cup  23  4 
tput  longname 


Initialize  the  terminal  according  to  the  type  of  terminal  in  the  environmental  vari¬ 
able  TERM.  This  command  can  be  included  in  a  .profile  or  .login  file. 

Reset  a  Sun  workstation  console,  shelltool(l)  window,  or  cmdtool(l)  window, 
overriding  the  type  of  terminal  in  the  environmental  variable  TERM. 

Send  the  sequence  to  move  the  cursor  to  row  0,  column  0  (the  upper  left  comer  of 
the  screen,  usually  known  as  the  “home”  cursor  position). 

Echo  the  dear-screen  sequence  for  the  current  terminal. 

Print  the  number  of  columns  for  the  current  terminal. 

Print  the  number  of  columns  for  the  Sun  workstation  console  or  subwindow. 


Set  the  shell  variables  bold,  to  begin  stand-out  mode  sequence,  and  offbold,  to 
end  standout  mode  sequence,  for  the  current  terminal.  This  might  be  followed  by 
a  prompt- 

echo  "${bold}Please  type  in  your  name:  ${offbold}\c" 

Set  exit  code  to  indicate  if  the  current  terminal  is  a  hardcopy  terminal. 

Send  the  sequence  to  move  the  cursor  to  row  23,  column  4. 

Print  the  long  name  from  the  terminfo  database  for  the  type  of  terminal  specified 
in  the  environmental  variable  TERM. 


FILES 

/usr/share/lib/terminfo/?/* 

compiled  terminal  description  database 
/usr/Sinclude/curses.h  curses(3V)  header  file 
/usr/5include/term.h  terminfo(5V)  header  file 

/usr/share/lib/tabset/*  TAB  settings  for  some  terminals,  in  a  format  appropriate  to  be  output  to  the  termi¬ 
nal  (escape  sequences  that  set  margins  and  TAB  characters);  for  more  information, 
see  the  Tabs  and  Initialization  section  of  tenninfo(5V). 

.login 

.profile 


SEE  ALSO 

cmdtool(l),  shelltool(l),  stty(lV),  curses(3V),  terminfo(5V) 
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NAME 

tr  -  translate  characters 
SYNOPSIS 

tr  [  -cds  ]  [  stringl  [  string2  ]  ] 

SYSTEM  V  SYNOPSIS 

/usr/5bin/tr  [  -cds  ]  [  stringl  [  stringl  ]  ] 

AVAILABILITY 

The  System  V  version  of  this  command  is  available  with  the  System  V  software  installation  option.  Refer 
to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

tr  copies  the  standard  input  to  the  standard  output  with  substitution  or  deletion  of  selected  characters.  The 
arguments  stringl  and  stringl  are  considered  sets  of  characters.  Any  input  character  found  in  stringl  is 
mapped  into  the  character  in  the  corresponding  position  within  stringl .  When  stringl  is  short,  it  is  padded 
to  the  length  of  stringl  by  duplicating  its  last  character. 

In  either  string  the  notation: 
a-b 

denotes  a  range  of  characters  from  a  to  bin  increasing  ASCII  order.  The  character  \ ,  followed  by  1, 2  or  3 
octal  digits  stands  for  the  character  whose  ASCII  code  is  given  by  those  digits.  As  with  the  shell,  the  escape 
character  \ ,  followed  by  any  other  character,  escapes  any  special  meaning  for  that  character. 

SYSTEM  V  DESCRIPTION 

When  stringl  is  short,  characters  in  stringl  with  no  corresponding  character  in  stringl  are  not  translated. 

In  either  string  the  following  abbreviation  conventions  introduce  ranges  of  characters  or  repeated  charac¬ 
ters  into  the  strings.  Note:  in  the  System  V  version,  square  brackets  are  required  to  specify  a  range. 

[a-z]  Stands  for  the  string  of  characters  whose  ASCII  codes  run  from  character  a  to  character  z,  in¬ 
clusive. 

[a*n]  Stands  for  n  repetitions  of  a.  If  the  first  digit  of  « is  0,  n  is  considered  octal;  otherwise,  n  is  taken 
to  be  decimal.  A  zero  or  missing  n  is  taken  to  be  huge;  this  facility  is  useful  for  padding  stringl . 

OPTIONS 

Any  combination  of  the  options  -c,  -d,  or  -s  may  be  used: 

-c  Complement  the  set  of  characters  in  stringl  with  respect  to  the  universe  of  characters  whose 
ASCn  codes  are  01  through  0377  octal; 

-d  Delete  all  input  characters  in  stringl . 

-s  Squeeze  all  strings  of  repeated  output  characters  that  are  in  stringl  to  single  characters. 

EXAMPLE 

The  following  example  creates  a  list  of  all  the  words  in  Jilenamel  one  per  line  in  filenamely  where  a  word 
is  taken  to  be  a  maximal  string  of  alphabetics.  The  second  string  is  quoted  to  protect  ‘  \  ’  from  the  shell, 
012  is  the  ASCn  code  for  NEWLINE. 

tr  -cs  A-Za-z  '\012'  <  jilenamel  > Jilenamel 

In  the  System  V  version,  this  would  be  specified  as: 

tr-cs  lA-Z][a-z]'  '[\012*]'  < Jilenamel >  jilenamel 
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SEE  ALSO 

ed(l),  expand(l),  ascii(7) 

BUGS 

Will  not  handle  ASCn  NUL  in  stringl  or  string2.  tr  always  deletes  NUL  from  input. 
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NAME 

trace  •“  trace  system  calls  aad  signals 
SYNOPSIS 

trace  [  -ct  ]  [  -o  filename  ]  command 
trace  [  — ct  ]  [  -o  filename  ]  -p  pid 
DESCRIPTION 

trace  runs  the  specified  command  until  it  exits.  It  intercepts  the  system  calls  and  signals  of  a  process.  The 
name  of  the  system  call,  its  arguments  and  result  are  listed  on  the  standard  oulput. 

Each  line  in  the  trace  contains  the  system  call  name,  followed  by  its  arguments  in  parentheses  and  its  result. 
Error  returns  (result  =  -1)  have  the  error  name  and  error  message  appended.  Signals  are  printed  as  a  signal 
name  followed  by  the  signal  number.  Arguments  are  printed  according  to  their  type.  Structure  pointers  are 
always  printed  as  hex  addresses.  Character  pointers  are  dereferenced  and  printed  as  a  quoted  string.  Non¬ 
printing  characters  in  strings  are  represented  by  escape  codes.  Only  the  first  32  bytes  of  strings  are  printed; 
longer  strings  have  two  dots  appended  following  the  closing  quote. 

The  quick  brown  fox  jumps  over  t  . . 

Strings  with  more  than  50%  non-printing  characters  are  assumed  to  contain  binary  data  and  are  represented 
by  a  null  string  followed  by  two  dots. 


Print  a  quick  summary  of  system  call  and  signal  counts,  instead  of  printing  a  full  trace. 

Prefix  each  line  of  the  trace  with  the  time  of  day. 

Write  the  trace  ouq)ut  to  the  file  filename  rather  than  to  the  standard  output. 

Attach  to  the  process  with  the  process  ID  pid  and  begin  tracing.  The  trace  may  be  ter¬ 
minated  at  any  time  by  a  keyboard  interrupt  signal  (CTRL-C);  trace  will  respond  by  detach¬ 
ing  itself  from  the  traced  process  leaving  it  to  continue  running, 

EXAMPLES 

example  %  trace  date 
gettimeofday  (0x21474, 0x2 147c)  ~  0 
gettimeofday  (0x21474, 0)  =  0 
gettimeofday  (0xefffc78, 0x214ac)  =  0 

ioctl  (1, 0x40067408,  OxefffalO)  =  -1  ENOTTY  (Inappropriate  ioctl  for  device) 

fstat(l,0xefffa30)  =  0 

getpagesize  0  = 

brk  (0x27640)  =  0 

close  (0)  =  0 

Thu  Dec  4  14:16:36  PST  1986 

write  (1,  "Thu  Dec  4  14:16:36  PST  1986\n",  29)  =  29 

close  (1)  =  0 

close  (2)  =  0 

exit  (0)  =  ? 

exam  pie  % 

SEE  ALSO 

ptrace(2) 


OPTIONS 

-c 


-t 

-o  filename 
-ppid 
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NOTES 

A  process  that  has  a  system  call  trace  applied  to  it  with  the  -p  option  will  receive  a  SIGSTOP.  This  signal 
may  interrupt  a  system  call  that  is  not  restartable.  This  may  have  an  unpredictable  effect  on  the  process  if 
the  process  takes  no  action  to  restart  the  system  call. 

BUGS 

Programs  that  use  the  setuid  bit  do  not  have  effective  user  ID  privileges  while  being  traced. 

Child  processes  of  a  traced  process  are  not  traced. 

A  traced  process  ignores  SIGSTOP. 

A  traced  process  runs  slowly. 
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NAME 

traffic  -  SunView  program  to  display  Ethernet  traffic 
SYNOPSIS 

traffic  [  -h  host  ]  [  -s  subwindows  ] 

AVAILABILITY 

This  command  is  available  when  both  the  Networ Icing  and  the  SunView  User's  software  options  are  in¬ 
stalled,  Refer  to  Installing  SunOS  4.1  for  information  on  how  to  install  optional  software. 

DESCRIPTION 

traffic  graphically  displays  ethemet  traffic.  It  gets  statistics  from  etherd(8C),  running  on  machine  host. 
The  tool  is  divided  into  subwindows,  each  giving  a  different  view  of  network  traffic. 

OPTIONS 

-h  host  Specify  a  host  from  which  to  get  statistics.  The  default  value  of  host  is  the  machine  that 

traffic  is  running  on. 

-s  subwindows  Specify  the  number  of  subwindows  to  display  initially.  The  default  value  of  subwindows 
is  1, 

SUBWINDOWS 

To  the  right  of  each  subwindow  is  a  panel  that  selects  what  the  subwindow  is  viewing.  When  Size  is 
checked,  than  the  size  distribution  of  packets  is  displayed.  Proto  is  for  protocol,  Src  is  for  source  of  pack¬ 
et,  and  Dst  is  for  destination  of  packet.  Since  it  is  not  possible  to  show  all  possible  sources,  when  Src  is 
selected,  only  the  8  highest  sources  are  displayed  (and  similarly  for  Dst ). 

For  each  of  these  choices,  the  distribution  is  displayed  by  a  histogram.  The  panel  above  each  subwindow 
controls  characteristics  of  the  histograms.  At  the  left  of  the  panel  is  a  shaded  square,  corresponding  to  one 
of  the  two  shades  of  bars  in  the  histogram.  You  can  switch  the  shade  by  either  clicking  on  the  square  with 
the  left  button,  or  bringing  up  a  menu  over  the  square  with  the  right  mouse  button.  When  the  light  colored 
square  is  visible,  then  the  slider  in  the  center  of  the  panel  controls  how  often  the  light  colored  bars  are  up¬ 
dated.  When  the  dark  square  is  visible,  then  the  slider  refers  to  the  dark  bars  of  the  histogram.  To  the  right 
of  the  slider  is  a  choice  of  Abs  versus  Rel.  This  selects  whether  the  height  of  the  histogram  is  Absolute  in 
packets  per  second,  or  Relative  in  percent  of  total  packets  on  the  ethemet.  Next  in  the  panel  are  three  small 
horizontal  bars.  When  selected  (that  is,  when  a  check  mark  appears  to  the  left  of  the  three  bars),  a  horizon¬ 
tal  grid  appears  on  the  histogram.  Finally  the  button  marked  Delete  Me  will  delete  the  subwindow. 

The  right  hand  panel  also  has  a  choice  for  Load  Load  is  represented  as  a  strip  chart,  rather  than  a  histo¬ 
gram.  The  maximum  value  of  the  graph  represents  a  load  of  100%,  that  is  10  megabits  per  second  on  the 
ethemet.  When  Load  is  selected,  there  is  only  one  slider,  and  no  Rel  versus  Abs  choice. 

At  the  very  top  of  the  tool  is  a  panel  that  contains  filters,  as  well  as  a  Split  button  that  splits  the  tool  and 
creates  a  new  subwindow,  and  a  Quit  button  that  exits  the  tool.  The  filters  apply  to  all  the  subwindows. 
When  a  filter  is  selected,  a  check  mark  appears  to  the  left  of  the  word  Filter.  There  can  be  more  than  one 
filter  active  at  the  same  time.  The  meaning  of  each  filter  is  as  follows.  Src  is  a  host  or  net,  which  can  be 
specified  either  by  name  or  address  (similarly  for  Dst).  Proto  is  an  ip  protocol,  and  can  either  be  a  name 
(such  as  udp,  icmp)  or  a  number.  Lnth  is  either  a  packet  length,  or  a  range  of  lengths  separated  by  a  dash, 

SEE  ALSO 

etherd(8C) 

BUGS 

If  multiple  copies  of  traffic  are  using  the  same  copy  of  etherd,  and  one  of  them  invokes  a  filter,  then  all  the 
copies  of  traffic  will  be  filtered. 
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NAME 

troff  -  typeset  or  format  documents 
SYNOPSIS 

troff  [  -abfiqtwz  ]  [  -mpackage  ]  [  -nN  ]  [  -opagelist  ]  [  -pN  ]  [  -roN  ] 

[  ~sA^  ]  [filenames  ] . , . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.2  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

troff  formats  text  in  \ht  filenames.  For  historical  reasons,  output  goes  to  a  CAT/4  phototypesetter  attached 
to  /dev/cat,  but  nobody  uses  a  CAT/4  anymore.  Ordinarily,  postprocessing  software  converts  output  to  a 
form  that  can  be  printed  on  newer  typesetters  or  laser  printers.  Default  font  width  tables  correspond  to 
Times  Roman  on  PostScript™  printers.  See  also  the  nroff(l)  manual  page,  which  describes  a  formatter  for 
typewriter-like  devices. 

Input  to  troff  is  expected  to  consist  of  text  interspersed  with  formatting  requests  and  macros.  If  no 
filename  argument  is  present,  troff  reads  standard  input.  A  as  a  filename  argument  indicates  that  stan¬ 
dard  input  is  to  be  read  at  that  point  in  the  list  of  input  files;  troff  reads  the  files  named  ahead  of  the  in 
the  arguments  list,  then  text  from  the  standard  input,  and  then  text  from  the  files  named  after  the 

If  the  file  /etc/adm/tracct  is  writable,  troff  keeps  printer  accounting  records  there.  The  integrity  of  that 
file  may  be  secured  by  making  troff  a  “set-user-ID”  program  (see  chmod(lV)  for  details  on  the  setuid  per¬ 
mission  bit.) 

OPTIONS 

Options  may  appear  in  any  order,  but  they  all  must  appear  before  the  first  filename. 

-a  Send  a  printable  ASCII  approximation  of  the  results  to  the  standard  output. 

-i  Read  the  standard  input  after  the  input  files  are  exhausted. 

-q  Disable  echoing  during  a  .rd  request. 

-t  Direct  output  to  the  standard  output  instead  of  the  printer.  Since  this  output  is  non-ASCII 
it  is  generily  redirected  to  Ipr  -t. 

-mpackage 

Prepend  the  macro  file  /usT/\\b/im!kdtmac.package  to  the  input  filenames.  (Note  that 
most  references  to  macro  packages  include  the  leading  “m”  as  part  of  the  name;  the 
man(7)  macro  package  resides  in  /usr/lib/tmac/tmac.an). 

~nV  Number  first  generated  page  N. 

-olist  Print  only  pages  whose  page  numbers  appear  in  the  comma-separated  list  of  numbers  and 
ranges.  A  range  N-M  means  pages  N  through  Af ;  an  initial  -N  means  from  the  begin¬ 
ning  to  page  N ;  and  a  final  N-  means  from  V  to  the  end. 

-roN  Set  register  a  (one-character)  to  N. 

Some  options  of  troff  only  apply  if  you  have  a  CAT/4  typesetter  attached  to  your  system.  These  options 
remain  present  for  backward  compatibility.  However,  this  version  of  troff  does  not  support  this  typesetter 
by  default. 

-b  Report  whether  the  typesetter  is  busy  or  available.  No  text  processing  is  done. 

-f  Refrain  from  feeding  paper  out  and  stopping  at  the  end  of  the  print  job  on  the  typesetter, 

-w  Wait  until  typesetter  is  available,  if  currently  busy. 

-z  Suppress  all  formatted  output.  Display  only  terminal  messages  produced  by  .tm  requests 
and  diagnostics. 
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FILES 


pN  Print  all  characters  in  point  size  N  while  retaining  all  prescribed  spacings  and  motions,  to 
reduce  elapsed  time  on  the  typesetter. 

~~sN  Stop  the  phototypesetter  every  N  pages,  troff  produces  a  trailer  so  you  can  change 
cassettes;  resume  by  pressing  the  typesetter’s  start  button. 


/tmp/ta* 

/usr/lib/tmac/tmac.* 

/usr/Iib/terin/* 

/usr/lib/font/* 

/dev/cat 

/etc/adm/tracct 


temporary  file 

standard  macro  files 

terminal  driving  tables  for  nroff 

font  width  tables  for  alternate  mounted  troff  fonts 

phototypesetter 

accounting  statistics  for  /dev/cat 


SEE  ALSO 

checknr(l).  chinod(lV),  col<lV),  eqn(l),  Ipr(l),  nroff(l),  tbl(l),  printcap(5),  nian(7).  me(7),  ms(7), 
lpd(8) 


Formatting  Documents 
Using  nroff  and  troff 


DIAGNOSTICS 

No  /dev/cat:  try  -t  or  -a 

The  CAT/4  typesetter  is  not  accessible  from  your  machine.  Combine  the  ~t  option  of  troff  with 
the  -t  option  of  Ipr(l)  to  get  output  on  a  laser  printer  or  typesetter.  For  information  on  how  to 
inform  lpd(8)  of  a  PostScript  printer  attached  to  a  remote  host,  see  printcap(5). 

NOTES 

troff  is  not  8-bit  clean  because  it  is  by  design  based  on  7-bit  ASCII. 


Sun  Release  4.1 


Last  change:  21  December  1987 


609 


TRUE(l) 


USER  COMMANDS 


TRUE(l) 


NAME 

true,  false  -  provide  truth  values 

SYNOPSIS 

true 

false 

DESCRIPTION 

true  and  false  are  usually  used  in  a  Bourne  shell  script.  They  test  for  the  appropriate  status  “true”  or 
“false”  before  running  (or  failing  to  run)  a  list  of  commands. 

EXAMPLE 

The  following  Bourne  shell  script  will  be  executed  while  the  case  status  is  “true”, 
while  true 
do 

command  list 

done 

SEE  ALSO 

csh(l),  sh(l) 

EXIT  STATUS 

true  has  exit  status  0. 

false  has  exit  status  1. 
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NAME 

tset,  reset  -  establish  or  restore  terminal  characteristics 
SYNOPSIS 

tset  [  —InQrsS  ]  [  -ec  ]  [  “kc  ]  [  -m  [port ~1D  [  baudrate] :  type  ]  * . .  ]  [type] 

reset[-]  [-ec][-I]  [-kc]  [-11]  [-Q]  [-r]  [-s]  [-S] 

-m  [  indent  ]  [  test  baudrate  ]:  type  ] . . .  [  type  ] 

DESCRIPTION 

tset  sets  up  your  terminal,  typically  when  you  first  log  in.  It  does  terminal  dependent  processing  such  as 
setting  erase  and  kill  characters,  setting  or  resetting  delays,  sending  any  sequences  needed  to  properly  ini¬ 
tialized  the  terminal,  and  the  like,  tset  first  determines  the  type  of  terminal  involved,  and  then  does  neces¬ 
sary  initializations  and  mode  settings.  The  type  of  terminal  attached  to  each  port  is  specified  in  the 
/etc/ttytab  database.  Type  names  for  terminals  may  be  found  in  the  termcap(5)  database.  If  a  port  is  not 
wired  permanently  to  a  specific  terminal  (not  hardwired)  it  is  given  an  appropriate  generic  identifier  such  as 
dialup. 

reset  clears  the  terminal  settings  by  turning  off  CBREAK  and  RAW  modes,  output  delays  and  parity  check¬ 
ing,  turns  on  NEWLINE  ttanslation,  echo  and  TAB  expansion,  and  restores  undefined  special  characters  to 
their  default  state.  It  then  sets  the  modes  as  usual,  based  on  the  terminal  type  (which  will  probably  over¬ 
ride  some  of  the  above).  (See  stty(lV)  for  more  information.)  All  arguments  to  tset  may  be  used  with 
reset,  reset  also  uses  the  rs=  and  rf=  (reset  string  and  file)  instead  of  the  initialization  string  and  file  from 
/etc/termcap.  This  is  useful  after  a  program  dies  and  leaves  the  terminal  in  a  funny  state.  Often  in  this 
situation,  characters  will  not  echo  as  you  type  them.  You  may  have  to  type  ‘LINEFEED  reset  LINEFEED’ 
since  ‘RETURN’  may  not  work. 

When  no  arguments  are  specified,  tset  reads  the  terminal  type  from  the  TERM  environment  variable  and 
re-initializes  the  terminal,  and  performs  initialization  of  mode,  environment  and  other  options  at  login  time 
to  determine  the  terminal  type  and  set  up  terminal  modes. 

When  used  in  a  startup  script  (.profile  for  sh(l)  users  or  .login  for  csh(l)  users)  it  is  desirable  to  give  infor¬ 
mation  about  the  type  of  terminal  you  will  usually  use  on  ports  that  are  not  hardwired.  These  ports  are 
identified  in  /etc/tfyab  as  dialup  or  plugboard,  etc.  Any  of  the  alternate  generic  names  given  in 
/etc/termcap  may  be  used  for  the  identifier.  Refer  to  the  -m  option  under  OPTIONS  for  more  information. 
If  no  mapping  applies  and  a  final  type  option,  not  preceded  by  a  -m,  is  given  on  the  command  line  then 
that  type  is  used;  otherwise  the  type  found  in  the  /etc/ttytab  database  is  used  as  the  terminal  type.  This 
should  always  be  the  case  for  hardwired  ports. 

It  is  usually  desirable  to  return  the  terminal  type,  as  finally  determined  by  tset,  and  information  about  the 
terminal’s  capabilities,  to  a  shell’s  environment.  This  can  be  done  using  the  -,  -s,  or  ~S  options.  (Refer  to 
OPTIONS  for  more  information.) 

For  the  Bourne  shell,  put  this  command  in  your  .profile  file: 
eval  'tset  -s  options... ' 

or  using  the  C  shell,  put  this  command  in  your  .login  file: 
eval  'tset  -s  options... ' 

With  the  C  shell,  it  is  also  convenient  to  make  an  alias  in  your  .cshrc  file: 

alias  tset  'eval  'tset  -s  \!*'' 

This  also  allows  the  command: 
tset  2621 

to  be  invoked  at  any  time  to  set  the  terminal  and  environment.  Note  to  Bourne  Shell  users:  It  is  not  possi¬ 
ble  to  get  this  aliasing  effect  with  a  shell  script,  because  shell  scripts  cannot  set  the  environment  of  their 
parent.  If  a  process  could  set  its  parent’s  environment,  none  of  this  nonsense  would  be  necessary  in  the 
first  place. 
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Once  the  terminal  type  is  known,  tset  sets  the  terminal  driver  mode.  This  normally  involves  sending  an 
initialization  sequence  to  the  terminal,  setting  the  single  character  erase  (and  optionally  the  line-kill  (full 
line  erase))  characters,  and  setting  special  character  delays.  TAB  and  NEWLINE  expansion  are  turned  off 
during  transmission  of  the  terminal  initialization  sequence. 

On  terminals  that  can  backspace  but  not  overstrike  (such  as  a  CRT),  and  when  the  erase  character  is  *#’,  the 
erase  character  is  changed  as  if  -e  had  been  used. 

OPTIONS 

-  The  name  of  the  terminal  finally  decided  upon  is  output  on  the  standard  output.  This  is  intended 
to  be  captured  by  the  shell  and  placed  in  the  TERM  environment  variable. 

-ec  Set  the  erase  character  to  be  the  named  character  c  on  all  terminals.  Default  is  the  backspace  key 
on  the  keyboard,  usually  (CTRL-H),  The  character  c  can  either  be  typed  directly,  or  entered 
using  the  circumflex-character  notation  used  here. 

~\c  Set  the  interrupt  character  to  be  the  named  character  c  on  all  terminals.  Default  is  "C  (CTRL-C). 
The  character  c  can  either  be  typed  directly,  or  entered  using  the  circumflex-character  notation 
used  here. 

-I  Suppress  transmitting  terminal-initialization  strings. 

-kc  Set  the  line  kill  character  to  be  the  named  character  c  on  all  terminals.  Default  is  "U  (CTRL-U). 
The  kill  character  is  left  alone  if  -k  is  not  specified.  Control  characters  can  be  specified  by 
prefixing  the  alphabetical  character  with  a  circumflex  (as  in  CTRL-U)  instead  of  entering  the 
actual  control  key  itself.  This  allows  you  to  specify  control  keys  that  are  currently  assigned. 

-n  Specify  that  the  new  tty  driver  modes  should  be  initialized  for  this  terminal.  Probably  useless 
since  stty  new  is  the  default 

-Q  Suppress  printing  the  "Erase  set  to’  and  "Kill  set  to’  messages. 

-r  In  addition  to  other  actions,  reports  the  terminal  type. 

-s  Output  commands  to  set  and  export  TERM  and  TERM  CAP.  This  can  be  used  with 
set  noglob 
eval  'tset-s 
unset  noglob 

to  bring  the  terminal  information  into  the  environment.  Doing  so  makes  programs  such  as  vi(l) 
start  up  faster.  If  the  SHELL  environment  variable  ends  with  csh,  C  shell  commands  are  output, 
otherwise  Bourne  shell  commands  are  output. 

-S  Similar  to  the  -s  option,  but  produces  two  strings  containing  suitable  values  for  the  (environment) 
variables  TERM  and  TERMCAP,  respectively,  and  can  be  used  as  follows: 
set  noglob 
set  t=('tset  “S . . .') 
setenv  TERM  $t[l] 
setenv  TERMCAP  "$t[2]” 
unset  t 
unset  noglob 

Since  -s  loads  these  values,  its  use  is  preferred.  If  the  SHELL  environment  variable  does  not  end 
with  csh,  -S  produces  the  same  Bourne  shell  commands  that  -s  does. 
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-m  [portADlbaudratey.type] , . . 

Specify  (map)  a  terminal  type  when  connected  to  a  generic  port  (such  as  dialup  or  plugboard) 
identified  by  port-ID.  The  baudrate  argument  can  be  used  to  check  the  baudrate  of  the  port  and 
set  the  terminal  type  accordingly.  The  target  rate  is  prefixed  by  any  combination  of  the  following 
operators  to  specify  the  conditions  under  which  the  mapping  is  made: 

>  Greater  than 

@  Equals  or  “at” 

<  Less  than 

!  It  is  not  the  case  that  (negates  the  above  operators) 

?  Prompt  for  the  terminal  type.  If  no  response  is  given,  then  type  is  selected  by 

default. 

In  the  following  example,  the  terminal  type  is  set  to  adm3a  if  the  port  is  a  dialup  with  a  speed  of 
greater  than  300  or  to  dw2  if  the  port  is  a  dialup  at  300  baud  or  less.  In  the  third  case,  the  question 
mark  preceding  the  terminal  type  indicates  that  the  user  is  to  verify  the  type  desired.  A  null 
response  indicates  that  the  named  type  is  correct.  Otherwise,  the  user’s  response  is  taken  to  be  the 
type  desired. 

tset— m  ’dialup>300:adm3a’  — m  ’dialup:dw2’  — m  ’plugboard:?adn[i3a’ 

To  prevent  interpretation  as  metacharacters,  the  entire  argument  to  -m  should  be  enclosed  in  sin¬ 
gle  quotes.  When  using  the  C  shell,  exclamation  points  should  be  preceded  by  a  backslash  (\). 

EXAMPLES 

These  examples  all  use  the  ’  option.  A  typical  use  of  tset  in  a  .profile  or  .login  will  also  use  the  — e  and 
— k  options,  and  often  the  — n  or  -Q  options  as  well.  These  options  have  been  omitted  here  to  keep  the 
examples  short. 

To  select  a  2621,  you  might  put  the  following  sequence  of  commands  in  your  .login  file  (or  .profile  for 
Bourne  shell  users). 

set  noglob 
eval  tset  -s  2621' 
unset  noglob 

If  you  have  an  h  19  at  home  which  you  dial  up  on,  but  your  office  terminal  is  hardwired  and  known  in 
/etc/ttytab,  you  might  use: 
set  noglob 

eval  'tset  -s  -m  dialup:hl9' 
unset  noglob 

If  you  have  a  switch  which  connects  to  various  ports  (making  it  impractical  to  identify  which  port  you  may 
be  connected  to),  and  use  various  terminals  from  time  to  time,  you  can  select  from  among  those  terminals 
according  to  the  speed  or  baud  rate.  In  the  example  below,  tset  will  prompt  you  for  a  terminal  type  if  the 
baud  rate  is  greater  than  1200  (say,  9600  for  a  terminal  connected  by  an  RS-232  line),  and  use  a  Wyse  50 
by  default.  If  the  baud  rate  is  less  than  or  equal  to  1200,  it  will  select  a  2621.  Note  the  placement  of  the 
question  mark,  and  the  quotes  to  protect  the  >  and  ?  from  interpretation  by  the  shell, 
set  noglob 

eval  'tset  -s  -m  *switch>1200:?wy’  -m  ’switch<=1200:2621’' 
unset  noglob 

All  of  the  above  entries  will  fall  back  on  the  terminal  type  specified  in  /etc/ttytab  if  none  of  the  conditions 
hold.  The  following  entry  is  appropriate  if  you  always  dial  up,  always  at  the  same  baud  rate,  on  many  dif¬ 
ferent  kinds  of  terminals,  and  the  terminal  you  use  most  often  is  an  adm3a. 
set  noglob 

eval  'tset  -s  ?adm3a' 
unset  noglob 
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If  the  file  /etc/ttytab  is  not  properly  set  up  and  you  want  to  make  the  selection  based  only  on  the  baud  rate, 
you  might  use  the  following; 
set  noglob 

eval  'tset  -s  -m  ’>1200:wy’  2621' 
unset  noglob 

The  following  example  quietly  sets  the  erase  character  to  BACKSPACE,  and  kill  to  CTRL-U.  If  the  port  is 
switched,  it  selects  a  Concept  100  for  speeds  less  than  or  equal  to  1200,  and  asks  for  the  terminal  type  oth¬ 
erwise  (the  default  in  this  case  is  a  Wyse  50).  If  the  port  is  a  direct  dialup,  it  selects  Concept  100  as  the  ter¬ 
minal  type.  If  logging  in  over  the  TCP/IP,  the  terminal  type  selected  is  a  Datamedia  2500  terminal  or  emu¬ 
lator.  (Note  the  backslash  escaping  the  NEWLINE  at  the  end  of  the  first  line  in  the  example.) 

set  noglob 

eval  'tset  -e  -k*U  -Q  -s  -m  ’switch<=1200:conceptI00’  -m  \  ’switch:?wy’  -m 

dialup:conceptl00  -m  arpanet:dni2500' 
unset  noglob 

FTLES 

/etc/ttytab 
/etc/termcap 
/usr/share/lib/tabset/* 

.login 
.profile 

SEE  ALSO 

csh(l),  sh(l),  stty(lV),  vi(l),  environ(5V),  ternicap(5),  ttytab(5) 

NOTES 

Once  the  terminal’s  size  has  been  initialized,  further  invocations  of  tset  will  not  affect  it.  To  correct  this, 
do  the  following: 

example  %  stty  rows  0  colums  0 

and  then  run  tset  normally. 

BUGS 

The  tset  command  is  one  of  the  first  commands  a  user  must  master  when  getting  started  on  a  UNDC  system. 
Unfortunately,  it  is  one  of  the  most  complex,  largely  because  of  the  extra  effort  the  user  must  go  through  to 
get  the  environment  of  the  login  shell  set.  Something  needs  to  be  done  to  make  all  this  simpler,  either  the 
login  program  should  do  this  stuff,  or  a  default  shell  alias  should  be  made,  or  a  way  to  set  the  environment 
of  the  parent  should  exist. 

This  program  cannot  intuit  personal  choices  for  erase,  interrupt  and  line  kill  characters,  so  it  leaves  these 
set  to  the  local  system  standards. 

It  could  well  be  argued  that  the  shell  should  be  responsible  for  ensuring  that  the  terminal  remains  in  a  sane 
state;  this  would  eliminate  the  need  for  the  reset  program. 


port  name  to  terminal  type  mapping  database 
terminal  capability  database 

TAB  setting  sequences  for  various  terminals.  Pointed  to  by  termcap  entries. 
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NAME 

tsort  -  topological  sort 

SYNOPSIS 

tsort  [filename  ] 

DESCRIPTION 

tsort  produces  on  the  standard  output  a  totally  ordered  list  of  items  consistent  with  a  partial  ordering  of 
items  mentioned  in  the  input  filename.  If  no  filename  is  specified,  the  standard  input  is  understood. 

The  input  consists  of  pairs  of  items  (nonempty  strings)  separated  by  SPACE  characters.  Pairs  of  different 
items  indicate  ordering.  Pairs  of  identical  items  indicate  presence,  but  not  ordering. 

SEE  ALSO 

lorder(l) 

BUGS 

Uses  a  quadratic  algorithm;  not  worth  fixing  for  the  typical  use  of  ordering  a  library  archive  file. 
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NAME 

tty  -  display  the  name  of  the  terminal 

SYNOPSIS 

tty  [-S] 

DESCRIPTION 

tty  prints  the  pathname  of  the  user’s  terminal  unless  the  -s  (silent)  option  is  given.  In  either  case,  the  exit 
value  is  zero  if  the  standard  input  is  a  terminal,  and  one  if  it  is  not. 

OPTIONS 

-s  Silent.  Does  not  print  the  pathname  of  the  user’s  terminal. 


616 


Last  change:  9  September  1987 


Sun  Release  4.1 


UL(1) 


USER  COMMANDS 


UL(1) 


NAME 

ul  ~  do  underlining 
SYNOPSIS 

ul  [ -i  ]  [ -t  terminal  ]  [filename. . .  ] 

DESCRIPTION 

ul  reads  the  named  filenames  (or  the  standard  input  if  none  are  given)  and  translates  occurrences  of  under¬ 
scores  to  the  sequence  which  indicates  underlining  for  the  terminal  in  use.  as  specified  by  the  environment 
variable  TERM,  ul  uses  the  /etc/termcap  file  to  determine  the  appropriate  sequences  for  underlining.  If  the 
terminal  is  incapable  of  underlining,  but  is  capable  of  a  standout  mode  then  that  is  used  instead.  If  the  ter¬ 
minal  can  overstrike,  or  handles  underlining  automatically,  ul  degenerates  to  cat(lV).  If  the  terminal  can¬ 
not  underline,  underlining  is  ignored. 

OPTIONS 

-t  terminal 

Override  the  terminal  kind  specified  in  the  environment  If  the  terminal  cannot  underline,  under- 
lining  is  ignored. 

“1  Indicate  underlining  by  a  separate  line  containing  appropriate  dashes  this  is  useful  when  you 
want  to  look  at  the  underlining  which  is  present  in  an  nroff(l)  output  stream  on  a  CRT-tenninal. 

FILES 

/etc/termcap 
SEE  ALSO 

cat(lV),  colcrt(l),  man(l),  nrolT(l) 

BUGS 

nroff  usually  generates  a  series  of  backspaces  and  underlines  intermixed  with  the  text  to  indicate  underlin¬ 
ing.  ul  makes  attempt  to  optimize  the  backward  motion. 
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NAME 

uname  -  display  the  name  of  the  current  system 

SYNOPSIS 

uname  [  -mnrsva  ] 

DESCRIPTION 

uname  prints  infonnation  about  the  current  system  on  the  standard  oulpuL  If  no  options  are  specified, 
uname  prints  the  current  system’s  name. 

OPTIONS 

-m  Print  the  machine  hardware  name. 

“R  Print  the  nodename.  The  nodename  may  be  a  name  that  the  system  is  known  by  to  a  communica¬ 
tions  network. 

-r  Print  the  operating  system  release. 

-s  Print  the  system  name  (default). 

-V  Print  the  operating  system  version. 

-a  Print  all  the  above  information. 

SEE  ALSO 

uname(2V) 
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NAME 

unifdef  -  resolve  and  remove  ifdefed  lines  from  cpp  input 
SYNOPSIS 

unifdef  [  -c  1 1  ]  [  -Dname  ]  [  -Vname  ]  [  -iHname  ]  [  -\\}nam€  ] . . .  [filename  ] 

DESCRIPTION 

unifdef  removes  ifdefed  lines  from  a  file  while  otherwise  leaving  the  file  alone.  It  is  smart  enough  to  deal 
with  the  nested  ifdefs.  comments,  single  and  double  quotes  of  C  syntax,  but  it  does  not  do  any  including  or 
interpretation  of  macros.  Neither  does  it  strip  out  comments,  though  it  recognizes  and  ignores  them.  You 
specify  which  symbols  you  want  defined  with  ~D  options,  and  which  you  want  undefined  with  ~U  options. 
Lines  within  those  ifdefs  will  be  copied  to  the  output,  or  removed,  as  appropriate.  Any  ifdef,  ifndef,  else, 
and  endif  lines  associated  with  filename  will  also  be  removed. 

ifdefs  involving  symbols  you  do  not  specify  are  untouched  and  copied  out  along  with  their  associated  ifdef, 
else,  and  endif  lines. 

If  an  ifdefY  occurs  nested  inside  another  ifdefY,  then  the  inside  ifdef  is  treated  as  if  it  were  an  unrecog¬ 
nized  symbol.  If  the  same  symbol  appears  in  more  than  one  argument,  only  the  first  occurrence  is 
significant. 

unifdef  copies  its  output  to  the  standard  output  and  will  take  its  input  from  the  standard  input  if  no  filename 
argument  is  given. 

OPTIONS 

-c  Complement  the  normal  operation.  Lines  that  would  have  been  removed  or  blanked  are  retained, 
and  vice  versa. 

-I  Replace  “lines  removed”  lines  with  blank  lines. 

”t  Plain  text  option,  unifdef  refrains  from  attempting  to  recognize  comments  and  single  and  double 
quotes, 

-IDname 

Ignore,  but  print  out,  lines  associated  with  the  defined  symbol  filename.  If  you  use  ifdefs  to  delimit 
non-C  lines,  such  as  comments  or  code  which  is  under  construction,  then  you  must  tell  unifdef 
which  symbols  are  used  for  that  purpose  so  that  it  won’t  try  to  parse  for  quotes  and  comments 
within  them. 

-iUname 

Ignore,  but  print  out,  lines  associated  with  the  undefined  symbol  filename. 

SEE  ALSO 

cpp(l),diff(l) 

DIAGNOSTICS 

Premature  EOF 

Inappropriate  else  or  endif. 

Exit  status  is  0  if  ouqDut  is  exact  copy  of  input,  1  if  not,  2  if  trouble. 

BUGS 

Does  not  know  how  to  deal  with  cpp(l)  constructs  such  as 
#if  defined(X)  ||  defined(Y) 


Sun  Release  4.1 


Last  change:  9  September  1987 


619 


UNIQ(l) 


USER  COMMANDS 


UNIQ(l) 


NAME 

uniq  “  remove  or  report  adjacent  duplicate  lines 
SYNOPSIS 

uniq  [  -cdu  [  +  l-w  ]  [  inputfile  [  outputfile  ]  ] 

DESCRIPTION 

uniq  reads  the  input  file  comparing  adjacent  lines.  In  the  normal  case,  the  second  and  succeeding  copies  of 
repeated  lines  are  removed;  the  remainder  is  written  on  the  output  file.  Note:  repeated  lines  must  be  adja¬ 
cent  in  order  to  be  found;  see  sort(lV). 

OPTIONS 

-c  Supersede  -u  and  -d  and  generate  an  output  report  in  default  style  but  with  each  line  preceded  by 
a  count  of  the  number  of  times  it  occurred. 

The  normal  output  of  uniq  is  the  union  of  the  -u  and  -d  options. 

-d  Write  one  copy  of  just  the  repeated  lines. 

-u  Copy  only  those  lines  which  are  not  repeated  in  the  original  file. 

The  n  arguments  specify  skipping  an  initial  portion  of  each  line  in  the  comparison: 

+n  The  first  n  characters  are  ignored.  Fields  are  skipped  before  characters. 

-n  The  first  n  fields  together  with  any  blanks  before  each  are  ignored.  A  field  is  defined  as  a  string 

of  non-SPACE,  non-TAB  characters  separated  by  SPACE  and  TAB  characters  from  its  neighbors. 

SEE  ALSO 

comm(l),  sort(lV) 
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NAME 

units  -  conversion  program 

SYNOPSIS 

units 

DESCRIPTION 

units  converts  quantities  expressed  in  various  standard  scales  to  their  equivalents  in  other  scales.  It  works 
interactively  in  this  fashion: 

You  have:  inch 
You  want:  cm 

♦  2.540000e+00 
/3.937008e-01 

A  quantity  is  specified  as  a  multiplicative  combination  of  units  optionally  preceded  by  a  numeric  multiplier. 
Powers  are  indicated  by  suffixed  positive  integers,  division  by  the  usual  sign: 

You  have:  15  lbs  force/in2 
You  want:  atm 

*  1.020689e+00 
/  9.797299e-01 

units  only  does  multiplicative  scale  changes.  Thus  it  can  convert  Kelvin  to  Rankine,  but  not  Celsius  to 
Fahrenheit.  Most  familiar  units,  abbreviations,  and  metric  prefixes  are  recognized,  together  with  a  gen¬ 
erous  leavening  of  exotica  and  a  few  constants  of  nature  including: 
pi  Ratio  of  circumference  to  diameter, 
c  Speed  of  light, 

e  Charge  on  an  electron, 

g  Acceleration  of  gravity, 

force  Same  as  g, 

mole  Avogadro’s  number, 

water  Pressure  head  per  unit  height  of  water, 
au  Astronomical  unit. 

pound  is  not  recognized  as  a  unit  of  mass;  lb  is.  pound  refers  to  a  British  pound.  Compound  names  are 
run  together  (for  instance,  lightyear).  British  units  that  differ  from  their  U.S.  counterparts  are  prefixed 
thus:  brgallon.  Currency  is  denoted  belgiumfranc,  britainpound, ...  For  a  complete  list  of  units,  type: 

cat  /usr/lib/units 

PILES 

/usr/lib/units 

BUGS 

Do  not  base  your  financial  plans  on  the  currency  conversions. 
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NAME 

unix2dos  -  convert  text  file  from  ISO  format  to  DOS  format 
SYNOPSIS 

unix2do$  [  -ascii  ]  [  -iso  ]  [  ~7  ]  originalfile  convertedfile 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0jic  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

unix2dos  converts  ISO  standard  characters  to  the  corresponding  characters  in  the  DOS  extended  character 
set. 

This  command  may  be  invoked  from  either  DOS  or  SunOS.  However,  the  filenames  must  conform  to  the 
conventions  of  the  environment  in  which  the  command  is  invoked. 

If  the  original  file  and  the  converted  file  are  the  same,  unix2dos  will  rewrite  the  original  file  after  convert¬ 
ing  it. 

OPTIONS 

-ascii  Adds  carriage  returns  and  converts  end  of  file  characters  in  SunOS  format  text  files  to  conform  to 
DOS  requirements. 

-iso  This  is  the  default.  Converts  ISO  standard  characters  to  the  corresponding  character  in  the  DOS 
extended  character  set. 

-7  Convert  8  bit  SunOS  characters  to  7  bit  DOS  characters. 

DIAGNOSTICS 

File  filename  not  found,  or  no  read  permission 

The  input  file  you  specified  does  not  exist,  or  you  do  not  have  read  permission  (check  with  the 
SunOS  command  Is  -1). 

Bad  output  filename  filename,  or  no  write  permission 

The  output  file  you  specified  is  either  invalid,  or  you  do  not  have  write  permission  for  that  file  or 
the  directory  that  contains  it.  Check  also  that  the  drive  or  diskette  is  not  write-protected. 

Error  while  writing  to  temporary  file 

An  error  occurred  while  converting  your  file,  possibly  because  there  is  not  enough  space  on  the 
current  drive.  Check  the  amount  of  space  on  the  current  drive  using  the  DIR  command.  Also  be 
certain  that  the  default  diskette  or  drive  is  write-enabled  (not  write-protected).  Note  that  when  this 
error  occurs,  the  original  file  remains  intact. 

Could  not  rename  tmpfile  to  filename. 

Translated  tmpfile  name  =  filename. 

The  program  could  not  perform  the  final  step  in  converting  your  file.  Your  converted  file  is  stored 
under  the  name  indicated  on  the  second  line  of  this  message. 

SEE  ALSO 

dos(l),  dos2unix(l) 

Sun386i  Advanced  Skills 
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NAME 

unload,  unloadc  -  unload  Application  SunOS  or  Developer’s  Toolkit  optional  clusters 
SYNOPSIS 

unload  filename. . . 

unloadc  duster. . . 

AVAILABILITY 

Available  only  on  Sun  386i  systems  running  a  SunOS  4.0jc  release  or  earlier.  Not  a  SunOS  4.1  release 
feature. 

DESCRIPTION 

unload  unloads  the  Application  SunOS  or  Developer’s  Toolkit  clusters  that  contain  the  specified  file  argu¬ 
ments.  unloadc  unloads  the  specified  Application  SunOS  or  Developer’s  Toolkit  clusters. 

Without  arguments,  unload  and  unloadc  display  a  summary  of  the  clusters  in  the  Application  SunOS  and 
Developer’s  Toolkit,  including  the  load  state  and  size  of  each  cluster. 

EXAMPLES 

To  unload  the  cluster  that  contains  the  spell  command: 
example  %  unload  spell 

About  to  unload  the  spellcheck  cluster,  confirm  (y/n):  y 
Unloading  the  spellcheck  cluster  ... 

The  spellcheck  cluster  has  been  unloaded, 
space  used  by  clusters:  5358K  bytes 
total  space  remaining:  20962K  bytes 
example  % 

To  display  a  summary  of  the  clusters  in  the  Application  SunOS  and  Developer’s  Toolkit 
example  %  unload 

Application  SunOS  Optional  Clusters: 
availablecluster  size  (bytes) 

yes  accounting  265K 

no  advanced  admin  501K 


Developer’s  Toolkit  Optional  Clusters: 
availablecluster  size  (bytes) 

no  basedevel  6907K 


space  used  by  clusters:  6021K  bytes 
total  space  remaining:  20432K  bytes 

FILES 

/export/cluster/sun386.sunosre/e£Z5£/appl 

where  Application  SunOS  clusters  are  loaded  (or  mounted),  release  is  the  current  release  of  the 
operating  system,  for  example,  4.0.2. 
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/export/cluster/sun386^unosre/ea5e/deveI 

where  Developer’s  Toolkit  clusters  are  loaded  (or  mounted),  release  is  the  current  release  of  the 
operating  system,  for  example,  4.0.2. 

/usr/lib/load/* 

data  files 

SEE  ALSO 

cluster(l),  load(l),  toc(5) 

Sun386i  Setup  and  Maintenance 
DIAGNOSTICS 

The  file  filename  is  not  in  any  of  the  optional  software  clusters. 

The  specified  file  is  not  part  of  the  Application  SunOS  or  Developer’s  Toolkit. 

The  cluster  cluster  is  not  loaded. 

The  specified  cluster  is  not  loaded  on  disk. 

There  is  no  cluster  cluster. 

The  specified  cluster  is  not  part  of  the  Application  SunOS  or  Developer’s  Toolkit. 

The  Application  SunOS  (and/or)  Developer’s  Toolkit  are  mounted. 

The  Application  SunOS  or  Developer’s  Toolkit  or  both  are  mounted  across  the  network  and  can 
not  be  loaded  or  unloaded. 
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NAME 

unwhiteout  -  remove  a  TFS  whiteout  entry 
SYNOPSIS 

unwhiteout  filename  . . . 

DESCRIPTION 

For  each  filename  that  is  a  whiteout  entry,  unwhiteout  removes  that  entry  from  the  containing  directory. 
These  whiteout  entries  are  created  by  the  translucent  file  service.  See  tfs(4S). 

SEE  ALSO 

Isw(l),  tfs(4S),  mount_tfs(8),  tfsd(8) 
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NAME 

uptime  -  show  how  long  the  system  has  been  up 

SYNOPSIS 

uptime 

DESCRIPTION 

uptime  prints  the  current  time,  the  length  of  time  the  system  has  been  up,  and  the  average  number  of  jobs 
in  the  run  queue  over  the  last  1, 5  and  15  minutes.  It  is,  essentially,  the  first  line  of  a  w(l)  command, 

EXAMPLE 

example  %  uptime 

6:47am  up  6  days,  16:38,  1  users,  load  average:  0.69, 0.28, 0.17 
example  % 

FILES 

/vmunix  system  namelist 

SEE  ALSO 

w(l) 
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NAME 

users  -  display  a  compact  list  of  users  logged  in 

SYNOPSIS 

users 

DESCRIPTION 

users  lists  the  login  names  of  the  users  currently  on  the  system  in  a  compact,  one-line  format; 
example  %  users 
paul  george  ringo 
example  % 

FILES 

/etc/utmp 

SEE  ALSO 

who(l) 
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NAME 

ustar  -  process  tape  archives 

SYNOPSIS 

/usr/Sbin/ustar  -c  [  bfvw  ]  device  block  filename  . . . 

/usr/Sbin/ustar  -r  [  bvw  ]  device  block  [filename . . .  ] 

/usr/Sbin/ustar  -t  [  fv  ]  device 
/usr/5bin/ustar  -u  [  bvw  J  device  block 
/usr/Sbin/ustar  -x  [  flmovw  ]  device  [filename ...  ] 

AVAILABILITY 

ustar  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  infor¬ 
mation  on  how  to  install  optional  software. 

DESCRIPTION 

ustar  reads  and  writes  archive  files  which  conform  to  the  Archive/Interchange  File  Format  specified  in 
IEEE  Std.  1003.M988. 

If  the  files  exist,  their  modes  are  not  changed  except  as  described  above.  The  owner,  group  and 
modification  time  are  restored  if  possible.  If  no  filename  argument  is  given,  the  entire  contents  of  the  ar¬ 
chive  is  extracted.  Note:  if  several  files  with  the  same  name  are  in  the  archive,  the  last  one  will  overwrite 
all  earlier  ones. 

OPTIONS 

-c  Create  a  new  archive;  writing  begins  at  the  beginning  of  the  archive,  instead  of  after  the  last  file. 

“r  Write  names  files  to  the  end  of  the  archive. 

-t  List  the  names  of  all  of  the  files  in  the  archive. 

-u  Add  named  files  to  the  archive  if  they  are  not  already  there,  or  if  they  have  been  modified  since 
last  written  into  the  archive.  This  implies  the  -r  option. 

-X  Extracts  named  files  from  the  archive.  If  a  named  file  matches  a  directory  whose  contents  had 
been  written  onto  the  archive,  that  directory  is  recursively  extracted.  If  a  named  file  in  the  archive 
does  not  exist  on  the  system,  the  file  is  create  with  the  same  mode  as  the  one  in  the  archive,  except 
that  the  set-user-id  and  get-group-id  modes  are  not  set  unless  the  user  has  appropriate  privileges. 

-b  Use  the  next  argument  on  the  command  line  as  the  blocking  factor  for  tape  records.  The  default  is 
1;  the  maximum  is  20.  This  option  should  only  be  used  with  raw  magnetic  tape  archives.  Nor¬ 
mally,  the  block  size  is  determined  automatically  when  reading  tapes. 

-f  Use  the  next  argument  on  the  command  line  as  the  name  of  the  archive  instead  of  the  default, 
which  is  usually  a  tape  drive.  If  is  specified  as  a  filename  ustar  writes  to  the  standard  output 
or  reads  from  the  standard  input,  whichever  is  appropriate  for  the  options  given.  Thus,  ustar  can 
be  used  as  the  head  or  tail  of  a  pipeline. 

-I  Report  if  ustar  cannot  resolve  all  of  the  links  to  the  files  being  archived.  If  -I  is  not  specified,  no 
error  messages  are  written  to  the  standard  output.  This  modifier  is  only  valid  with  the  -c,  -r  and 
-u  options. 

-m  Do  not  restore  the  modification  times.  The  modification  time  of  the  file  will  be  the  time  of  extrac¬ 
tion.  This  modifier  is  invalid  with  the  -t  option. 

-o  Extracted  files  take  on  the  user  and  group  identifier  of  the  user  running  the  program  rather  than 
those  on  the  archive.  This  modifier  is  only  valid  with  the  -x  option. 

-V  Verbose.  Print  the  name  of  each  file  it  processes,  preceded  by  the  option  letter.  With  the  -t  op¬ 
tion,  -V  gives  more  information  about  the  archive  entries  than  just  the  name. 
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-w  Print  the  action  to  be  taken,  followed  by  the  name  of  the  file,  and  then  wait  for  the  user’s 
confirmation.  If  a  word  beginning  with  y  is  given,  the  action  is  performed.  Any  other  input  im¬ 
plies  no  and  the  action  is  not  performed.  This  modifier  is  invalid  with  the  -t  option. 

FILES 

/dev/tty  used  to  prompt  the  user  for  information  when  the  -i  or  ~y  options  are  specified 

SEE  ALSO 

cpio(l),  dd(l),  find(l),  pax(lV),  paxcpio(l V),  cpio(5).  tar(5) 

AUTHOR 

Mark  H.  Colburn 
NAPS  International 
117  Mackubin  Street,  Suite  1 
St.  Paul,  MN  55102 

Sponsored  by  The  USENIX  Association  for  public  distribution. 
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NAME 

UUCP,  uulog,  uuname  -  system  to  system  copy 
SYNOPSIS 

UUCP  [  -cCdfjmr  ]  [  -ggrade  ]  [  -nusername  ]  [  -x  debugjevel  ]  source-file  . . .  destination-file 
uulog  [  -X  ]  [  -(system  ]  [  -ssystem  ]  [  -number  ] 
uuname  [  -cl  ] 

AVAILABILITY 

These  commands  are  available  with  the  uucp  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

uucp 

UUCP  copies  each  source-file  to  the  named  destination-file.  A  filename  may  be  a  path  name  on  your 
machine,  or  may  have  the  form 

system- name  Ipathname 

where  system-name  is  taken  from  a  list  of  system  names  that  uucp  knows  about.  The  system-name  may 
also  be  a  list  of  names  such  as 

system-namelsystem-namel. .  .Isystem-namelpathname 

in  which  case  an  attempt  is  made  to  send  the  file  by  way  of  the  specified  route,  to  the  destination.  See 
WARNINGS  and  BUGS  below  for  restrictions.  Care  should  be  taken  to  ensure  that  intermediate  nodes  in  the 
route  are  willing  to  foward  information  (see  WARNINGS  below  for  restrictions). 

The  shell  metacharacters  ?,  *,  and  [  ]  appearing  in  the  pathname  part  will  be  expanded  on  the  appropriate 
system. 

Path  names  may  be  one  of: 

•  a  full  pathname; 

•  a  pathname  preceded  by  "username  l\  username  is  interpreted  as  a  username  on  the  specified 
system  and  is  replaced  by  that  user’s  login  directory  on  that  system; 

•  a  pathname  preceded  by  'ldestinationl\  the  7  is  replaced  by  the  “public  UUCP”  directory  on 
the  remote  machine  Note:  this  destination  will  be  treated  as  a  file  name  unless  more  than  one 
file  is  being  transferred  by  this  request  or  the  destination  is  already  a  directory.  To  ensure 
that  it  is  a  directory,  follow  the  destination  with  a  For  example  7dan/  as  the  destination 
will  make  the  directory  /usr/spool/uucppublic/dan  if  it  does  not  exist  and  put  the  requested 
file(s)  in  that  directory; 

•  a  partial  pathname,  which  is  prefixed  by  the  pathname  of  current  directory. 

If  the  result  is  an  erroneous  pathname  for  the  remote  system,  the  copy  will  fail.  If  the  destination-file  is  a 
directory,  the  last  component  of  the  source-file  name  is  used. 

uucp  preserves  execute  permissions  across  the  transmission  and  gives  0666  read  and  write  permissions 
(see  chmod(2V)). 

uulog 

uulog  queries  the  log  file  /var/spool/uucp/.Log/uucico/syjfezw  of  uucp  transactions  for  system  system,  or 
the  log  file  /var/spool/uucp/Xog/uuxqt/.U'^tem  of  uux(lC)  transactions  for  system  system. 

uuname 

uuname  lists  the  UUCP  names  of  systems  that  can  be  accessed  using  uucp. 
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OPTIONS 

UUCP 

-c  Use  the  source  file  when  copying  out  rather  than  copying  the  file  to  the  spool  directory.  This  is  the 
default. 

-C  Make  a  copy  of  outgoing  files  in  the  UUCP  spool  directory,  rather  than  copying  the  source  file 
directly  to  the  target  system.  This  lets  you  remove  the  source  file  after  issuing  the  uucp  com¬ 
mand. 

-d  Make  all  necessary  directories  for  the  file  copy.  This  is  the  default. 

“f  Do  not  make  intermediate  directories  for  the  file  copy. 

“j  Output  the  job  identification  ASCH  string  on  the  standard  output.  This  job  identification  can  be 
used  by  uustat(lC)  to  obtain  the  status  or  terminate  a  job. 

-m  Send  mail  to  the  requester  when  the  copy  is  complete. 

-r  Do  not  start  uucico(8C),  just  queue  the  job. 

-ggrade 

grade  is  a  single  letter  or  number,  from  0  to  9,  A  to  Z,  or  a  to  z;  0  is  the  highest  grade,  and  z  is  the 
lowest  grade.  Lower  grades  will  cause  the  job  to  be  transmitted  earlier  during  a  particular  conver¬ 
sation.  The  default  grade  is  n.  By  way  of  comparison,  uux(lC)  defaults  to  A;  mail  is  usually  sent 
at  grade  C. 

-nusername 

Notify  username  on  the  remote  system  (that  is,  send  username  mail)  that  a  file  was  sent. 

-X  debug  Jevel 

Produce  debugging  output  on  the  standard  output,  debugjevel  is  a  number  between  0  and  9; 
higher  numbers  give  more  detailed  information.  5,  7,  and  9  are  good  numbers  to  try;  they  give 
increasing  amounts  of  detail. 

uulog 

-X  Look  in  the  uuxqt(8C)  log  file  for  the  given  system. 

-fsystem 

Does  a  ‘tail  -f’  of  the  file  transfer  log  for  system.  You  must  hit  BREAK  to  exit  this  function. 

-ssystem 

Print  information  about  work  involving  system  system. 

-number 

Indicate  that  a  tail  command  of  number  lines  should  be  executed. 

uuname 

— c  Display  the  names  of  systems  known  to  cu(lC).  The  two  lists  are  the  same,  unless  your  machine 

is  using  different  Systems  files  for  cu  and  uucp.  See  the  Sysfiles  file. 

-1  Display  the  local  system  name. 

FILES 

/var/spool/uucp  spool  directories 

/var/spool/uucppublic  public  directory  for  receiving  and  sending 
/ etc/ uucp/ ♦  other  data  files 

/usr/lib/uucp/*  other  program  files 

SEE  ALSO 

mail(l),  uustat(lC),  uux(lC),  chmod(2V),  uucico(8C),  uuxqt(8C) 
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WARNINGS 

The  domain  of  remotely  accessible  files  can  (and  for  obvious  security  reasons,  usually  should)  be  severely 
restricted.  You  will  very  likely  not  be  able  to  fetch  files  by  path  name;  ask  a  responsible  person  on  the 
remote  system  to  send  them  to  you.  For  the  same  reasons  you  will  probably  not  be  able  to  send  files  to 
arbitrary  path  names.  As  distributed,  the  remotely  accessible  files  are  those  whose  names  begin 
/usr/spool/uucppublic  (equivalent  to  “/). 

All  files  received  by  uucp  will  be  owned  by  the  user  ID  uucp. 

The  -m  option  will  only  work  sending  files  or  receiving  a  single  file.  Receiving  multiple  files  specified  by 
special  shell  characters  ?,  *,  and  [  ]  will  not  activate  the  -m  option. 

The  forwarding  of  files  through  other  systems  may  not  be  compatible  with  other  versions  of  UUCP.  If  for¬ 
warding  is  used,  all  systems  in  the  route  must  have  the  same  version  of  UUCP. 

When  invoking  uucp  from  csh(l),  the  !  character  must  be  prefixed  by  the  \  escape  to  inhibit  csh’s  history 
mechanism.  Quotes  are  not  sufficient. 

BUGS 

Protected  files  and  files  that  are  in  protected  directories  that  are  owned  by  the  requestor  can  be  sent  by 
uucp.  However,  if  the  requestor  is  root,  and  the  directory  is  not  searchable  by  “other”  or  the  file  is  not 
readable  by  “other”,  the  request  will  fail. 
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NAME 

uuencode,  uudecode  -  encode  a  binary  file,  or  decode  its  ASCII  representation 
SYNOPSIS 

uuencode  [  source-file  ]  file-label 
uudecode  [  encoded-file  ] 

DESCRIPTION 

uuencode  converts  a  binary  file  into  an  ASCn-encoded  representation  that  can  be  sent  using  mail(l).  It  en¬ 
codes  the  contents  of  source-file,  or  the  standard  input  if  no  source-file  argument  is  given.  Th&  file-label 
argument  is  required.  It  is  included  in  the  encoded  file’s  header  as  the  name  of  the  file  into  which 
uudecode  is  to  place  the  binary  (decoded)  data,  uuencode  also  includes  the  ownership  and  pennission 
modes  of  source-file,  so  that  file-label  is  recreated  with  those  same  ownership  and  permission  modes. 

If  the  remote  host  is  a  UNIX  system  with  the  sendniail(8)  mail-message  delivery  daemon,  you  can  pipe  the 
output  of  uuencode  through  mail(l)  to  the  recipient  named  decode  on  the  remote  host.  This  recipient  is 
typically  an  alias  for  the  uudecode  program  (see  aliases(5)  for  details),  which  allows  a  binary  file  to  be 
decoded  (extracted)  from  a  mail  message  automatically.  If  this  alias  is  absent  on  a  particular  host,  the  en¬ 
coded  file  can  be  mailed  to  a  user,  who  can  run  it  through  uudecode  manually. 

uudecode  reads  an  encoded-file ,  strips  off  any  leading  and  trailing  lines  added  by  mailer  programs,  and  re¬ 
creates  the  original  binary  data  with  the  filename  and  the  mode  and  owner  specified  in  the  header. 

The  encoded  file  is  an  ordinary  ASCII  text  file;  it  can  be  edited  by  any  text  editor.  But  it  is  best  only  to 
change  the  mode  or  file-label  in  the  header  to  avoid  corrupting  the  decoded  binary. 

SEE  ALSO 

mail(l),  uucp(lC),  uusend(lC),  uux(lC),  aliases(5),  uuencode(5),  sendmail(8) 

BUGS 

The  encoded  file’s  size  is  expanded  by  35%  (3  bytes  become  4,  plus  control  information),  causing  it  to  take 
longer  to  transmit  than  the  equivalent  binary. 

The  user  on  the  remote  system  who  is  invoking  uudecode  (typically  uucp)  must  have  write  permission  on 
the  file  specified  in  the  file-label. 

Since  both  uuencode  and  uudecode  run  with  user  ID  set  to  uucp,  uudecode  can  fail  with  “permission 
denied”  when  attempted  in  a  directory  that  does  not  have  write  permission  allowed  for  “other.” 
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NAME 

uusend  -  send  a  file  to  a  remote  host 
SYNOPSIS 

uusend  [  -fr  ]  [  -m  mode  ]  source-file  system-namel  \system-name2 !. .  .Idestination-file 
AVAILABILITY 

This  command  is  available  with  the  uucp  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  in¬ 
formation  on  how  to  install  optional  software. 

DESCRIPTION 

uusend  sends  the  file,  source-file y  to  a  given  location,  destination-file  y  on  a  remote  system.  The  system 
need  not  be  directly  connected  to  the  local  system,  but  a  chain  of  uucp(lC)  links  must  connect  the  two  sys¬ 
tems.  If  destination-file  is  a  directory,  the  last  component  of  the  source-file  name  is  used. 

The  source  file  can  be  meaning  to  use  the  standard  input.  These  options  are  primarily  intended  for 
internal  use  of  uusend. 

The  destination  file  can  include  the  "username  or  7  syntax. 

OPTIONS 

-f  Do  not  make  intermediate  directories  for  sending  the  file. 

-r  Do  not  start  uucico,  just  queue  the  job. 

-m  mode 

Take  the  mode  of  the  file  on  the  remote  end  from  the  octal  number  specified  as  mode.  The  mode 
of  the  input  file  is  used  if  the  -m  option  is  not  specified. 

SEE  ALSO 

uucp(lC),  uuencode(lC),  uux(lC) 

BUGS 

This  command  should  not  exist,  since  uucp  should  handle  it. 

All  systems  along  the  line  must  have  the  uusend  command  available  and  allow  remote  execution  of  it. 

Some  UUCP  systems  have  a  bug  where  binary  files  cannot  be  the  input  to  a  uux  command.  If  this  bug  ex¬ 
ists  in  any  system  along  the  line,  the  file  will  show  up  severely  corrupted. 
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NAME 

uustat  -  UUCP  status  inquiry  and  job  control 

SYNOPSIS 

uustat  -a  I-m  l-p  l~q  \-kjobid  \-xjobid 
uustat  [  ssystem  ]  [  -uuser  ] 

AVAILABILITY 

This  command  is  available  with  the  uucp  software  installation  option.  Refer  to  Installing  SunOS  4,2  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

uustat  displays  the  status  of,  or  cancels,  previously  specified  uucp(lC)  commands.  It  also  reports  the 
status  of  uucp  connections  to  other  systems.  When  no  options  are  given,  uustat  displays  the  status  of  all 
UUCP  requests  issued  by  the  current  user. 

OPTIONS 

Only  one  of  the  following  options  can  be  specified  at  a  time; 

-a  Output  all  jobs  in  queue. 

~m  Report  the  status  of  accessibility  of  all  machines. 

-p  Execute  a  ps  for  all  the  PIDs  listed  in  the  lock  files. 

-q  List  the  jobs  queued  for  each  machine.  If  a  status  file  exists  for  the  machine,  its  date,  time  and 

status  information  are  reported.  In  addition,  if  a  number  appears  in  parentheses  next  to  the 

number  of  C.  or  X.  files,  it  is  the  age  in  days  of  the  oldest  C./X.  file  for  that  system.  The  Retry 

field  represents  the  number  of  hours  until  the  next  possible  call.  The  Count  is  the  number  of 
failure  attempts.  For  systems  with  a  moderate  number  of  outstanding  jobs,  this  could  take  30 
seconds  or  more  to  execute.  An  example  of  the  output  from  -q  is: 

eagle  3C  04/07-11:07  NO  DEVICES  AVAILABLE 

inh3bs3  2C  07/07-10:42  SUCCESSFUL 

This  indicates  the  number  of  command  files  that  are  waiting  for  each  system.  Each  command  file 
may  have  zero  or  more  files  to  be  sent  (zero  means  to  call  the  system  and  see  if  work  is  to  be 
done).  The  date  and  time  refer  to  the  previous  interaction  with  the  system  followed  by  the  status 
of  the  interaction. 

-kjobid  Kill  the  UUCP  request  with  job  identification  of  jobid.  You  must  either  own  the  job  to  be  killed,  or 
be  the  super-user. 

—T jobid  Rejuvenate  The  files  associated  mth  jobid  are  touched  so  that  their  modification  time  is  set 

to  the  current  time.  This  prevents  the  cleanup  daemon  from  deleting  the  job  until  the  jobs 
modification  lime  reaches  the  next  limit  imposed  by  the  daemon. 

The  following  options  can  be  specified  separately  or  together: 

ssystem 

Report  the  status  of  all  UUCP  requests  for  remote  system  system. 

-uuser  Report  the  status  of  all  UUCP  requests  issued  by  user. 
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Output  for  both  the  -s  and  -u  options  has  the  following  format: 


eaglenOOOO  4/07-11:01:03  (POLL) 


eagleNlbd?  4/07-11:07 

s 

eagle 

dan 

522  /usr/dan/A 

eagleClbdS  4/07-11:07 

s 

eagle 

dan 

59  D.3b2al2ce4924 

4/07-11:07 

s 

eagle 

dan 

rmail  mike 

The  first  field  is  the  job  ID  of  the  job.  This  is  followed  by  the  date  and  time.  The  next  field  is  ei¬ 
ther  an  S  or  R  depending  on  whether  the  job  is  to  send  or  request  a  file.  This  is  followed  by  the 
user  ID  of  the  user  who  queued  the  job.  The  next  field  contains  the  size  of  the  file,  or  in  the  case 
of  a  remote  execution  request,  the  name  of  the  command.  When  the  size  appears  in  this  field,  the 
file  name  is  also  given.  This  can  either  be  the  name  given  by  the  user,  or  an  internal  name  created 
for  data  files  associated  with  remote  executions  (rmail  in  this  example). 

FILES 

/var/spool/uucp/*  UUCP  spool  directories 

SEE  ALSO 

uucp(lC) 
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NAME 

uuto,  uupick  “  public  system-to>system  file  copy 
SYNOPSIS 

uuto  [  -mp  ]  source-file  . . .  destination 
uupick  [  -s  system  ] 

AVAILABILITY 

This  command  is  available  with  the  uucp  software  installation  option.  Refer  to  Installing  SunOS  4J  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

uuto 

uuto  sends  source-files  to  destination,  uuto  uses  the  uucp(lC)  facility  to  send  files,  while  it  allows  the  lo¬ 
cal  system  to  control  the  file  access.  A  source-file  name  is  a  path  name  on  your  machine.  Destination  has 
the  form: 


system-name  lusername 

where  system-name  is  taken  from  a  list  of  system  names  that  uucp  knows  about  (see  uucp(lC)).  username 
is  the  username  of  someone  on  the  specified  system. 

The  files  (or  sub-trees  if  directories  are  specified)  are  sent  to  the  “public  UUCP”  directory  on  the  remote 
machine  system-name.  Normally,  this  directory  is  /usr/spool/uucppublic.  Specifically  the  files  are  sent  to 

y  VBJ)lR/r  eceiy  el  username  fmy  system /file 

where  PUBDIR  is  the  “public  UUCP”  directory  on  system-name,  mysystem  is  the  system  from  which  the 
files  are  sent,  and  file  is  the  file  being  sent. 

The  destined  recipient  is  notified  by  mail(l)  of  the  arrival  of  files. 


uupick 

uupick  accepts  or  rejects  the  files  transmitted  to  the  user.  Specifically,  uupick  searches  the  “public  UUCP” 
directory  on  the  local  machine  for  files  destined  for  the  user.  For  each  entry  (file  or  directory)  found,  the 
following  message  is  printed  on  the  standard  output: 

from  system :  [file  file-name]  [  dir  dirname]  ? 


uupick  then  reads  a  line  from  the  standard  input  to  determine  the  disposition  of  the  file: 


<NEWL[NE> 

d 

m  [  dir  ] 


a  [  dir  ] 

P 

q 


Go  on  to  next  entry. 

Delete  the  entry. 

Move  the  entry  to  named  directory  dir.  If  dir  is  not  specified  as  a  complete  path  name 
(in  which  $HOME  is  legitimate),  a  destination  relative  to  the  current  directory  is  as¬ 
sumed.  If  no  destination  is  given,  the  default  is  the  current  directory. 

Same  as  m  except  moving  all  the  files  sent  from  system. 

Print  the  content  of  the  file. 

Stop. 


EOT  (CTRL-D)  Same  as  q. 

[command  Escape  to  the  shell  to  do  command. 


Print  a  command  summary. 
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OPTIONS 

uuto 

-m  Send  mail  to  the  sender  when  the  copy  is  complete. 

“P  Copy  the  source  file  into  the  spool  directory  before  transmission. 

uupick 

-s  system 

Search  only  the  “public  UUCP”  directory  on  the  local  machine  for  files  sent  from  system. 

FILES 

/usr/spool/uucppublic  public  UUCP  directory 
SEE  ALSO 

mail(l),  uucp(lC),  uustat(lC),  uux(lC),  uucleanup(8C) 

WARNINGS 

In  order  to  send  files  that  begin  with  a  dot  (such  as»  .profile)  the  files  must  by  qualified  with  a  dot.  For  ex¬ 
ample:  .profile,  .prof*,  and  .profil?  are  correct,  whereas  *prof*  and  ?profile  are  incorrect. 
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NAME 

uux  -  remote  system  command  execution 
SYNOPSIS 

uux  [  -  ]  [  -bcCjnprz  ]  [  -aname  ]  [  -ggrade  ]  [  -x  debugjevel  ]  command-string 

AVAILABILITY 

This  command  is  available  with  the  uucp  software  installation  option.  Refer  to  Installing  SunOS  4.1  for 
information  on  how  to  install  optional  software. 

DESCRIPTION 

uux  will  gather  0  or  more  files  from  various  systems,  execute  a  command  on  a  specified  system  and  send 
the  standard  output  to  a  file  on  a  specified  system. 

For  security  reasons,  most  installations  limit  the  list  of  commands  executable  on  behalf  of  an  incoming 
request  from  uux,  permitting  only  the  receipt  of  mail  (see  mail(l)).  Remote  execution  permissions  are 
defined  in  /etc/uucp/Permissions. 

The  command-string  is  made  up  of  one  or  more  arguments  that  look  like  a  shell  command  line,  except  that 
the  command  and  file  names  may  be  prefixed  by  *system-namel  ’.  A  null  system-name  is  interpreted  as  the 
local  system. 

Path  names  may  be  one  of: 

•  a  full  pathname; 

•  a  pathname  preceded  by  "user name !;  username  is  interpreted  as  a  username  on  the  specified 
system  and  is  replaced  by  that  user’s  login  directory  on  that  system; 

•  a  pathname  preceded  by  '! destination! \  the  7  is  replaced  by  the  “public  UUCP”  directory  on 
the  remote  machine  Note:  this  destination  will  be  treated  as  a  file  name  unless  more  than  one 
file  is  being  transferred  by  this  request  or  the  destination  is  already  a  directory.  To  ensure 
that  it  is  a  directory,  follow  the  destination  with  a  7’.  For  example  7dan/  as  the  destination 
will  make  the  directory  /usr/spool/uucppublic/dan  if  it  does  not  exist  and  put  the  requested 
file(s)  in  that  directory; 

•  a  partial  pathname,  which  is  prefixed  by  the  pathname  of  current  directory. 

The  option  sends  the  standard  input  to  the  uux  command  as  the  standard  input  to  the  command-string. 

Any  special  shell  characters  such  as  and  |  should  be  quoted  either  by  quoting  the  entire  command¬ 
string,  or  by  quoting  the  special  characters  as  individual  arguments. 

uux  will  attempt  to  get  all  files  to  the  execution  system.  For  files  that  are  output  files,  the  file  name  must  be 
escaped  using  parentheses.  For  example,  the  command 

uux  alcut  -fl  bl/usr/file  \(cl/usr/file\) 

gets  /usr/file  from  system  b  and  sends  it  to  system  a,  performs  a  cut  command  on  that  file  and  sends  the 
result  of  the  cut  command  to  system  c. 

uux  will  notify  you  if  the  requested  command  on  the  remote  system  was  disallowed,  or  if  the  command 
fails  (that  is,  returns  a  non-zero  exit  status).  This  notification  can  be  turned  off  by  the  -n  option.  The 
response  comes  by  remote  mail  from  the  remote  machine. 

OPTIONS 

-b  Return  whatever  standard  input  was  provided  to  the  uux  command  if  the  job  fails  (that  is,  returns 
a  non-zero  exit  status). 

”C  Do  not  copy  local  file  to  the  spool  directory  for  transfer  to  the  remote  machine.  This  is  the  default. 

-C  Force  the  copy  of  local  files  to  the  spool  directory  for  transfer. 

~j  Output  the  jobid  ASCII  string  on  the  standard  output  which  is  the  job  identification.  This  job 

identification  can  be  used  by  uustat(lC)  to  obtain  the  status  or  terminate  a  job. 
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-n  Do  not  return  any  indication  by  mail(l)  of  success  or  failure  of  the  job. 

-p  Same  as  the  standard  input  to  uux  is  made  the  standard  input  to  the  command-string . 

-r  Do  not  start  uucico(8C),  just  queue  the  job. 

-z  Return  an  indication  by  mail  even  if  the  job  succeeds  (that  is,  returns  a  zero  exit  status). 

-mame  Use  name  as  the  user  identification  replacing  the  initiator  user  ID.  Notification  will  be  returned  to 
the  user. 

-ggrade 

grade  is  a  single  letter  or  number,  from  0  to  9,  A  to  Z,  or  a  to  z;  0  is  the  highest  grade,  and  z  is  the 
lowest  grade.  Lower  grades  will  transmit  the  job  earlier  during  a  particular  conversation.  The 
default  grade  is  A. 

-X  debugjevel 

Produce  debugging  output  on  the  standard  output,  debugjevel  is  a  number  between  0  and  9; 
higher  numbers  give  more  detailed  information.  5,  7,  and  9  are  good  numbers  to  try;  they  give 
increasing  amounts  of  detail. 

EXAMPLE 

The  command 

uux  "!diff  usgl/usr/dan/filel  pwba!/a4/dan/file2  >  r/dan/file.difr' 

will  get  the  filel  and  file2  files  from  the  usg  and  pwba  machines,  execute  a  diff(l)  command  and  put  the 
results  in  file.difT  in  the  local  PUBDIR/dan  directory. 

FILES 

/var/spool/uucp  spool  directories 

/etc/uucp/Permissions  remote  execution  permissions 

/etc/uucp/*  other  data 

/usr/lib/uucp/*  other  programs 

SEE  ALSO 

mail(l),  uucp(lC),  uustat(lC),  uucico(8C) 

System  and  Network  Administration 
WARNINGS 

Only  the  first  command  of  a  shell  pipeline  may  have  a  'sysiem-namel  ’.  All  other  commands  are  executed 
on  the  system  of  the  first  command. 

The  use  of  the  shell  metacharacter  ♦  will  probably  not  do  what  you  want  it  to  do. 

The  shell  tokens  «  and  »  are  not  implemented. 

The  execution  of  commands  on  remote  systems  takes  place  in  an  execution  directory  known  to  the  UUCP 
system.  All  files  required  for  the  execution  will  be  put  into  this  directory  unless  they  already  reside  on  that 
machine.  Therefore,  the  simple  file  name  (without  path  or  machine  reference)  must  be  unique  within  the 
uux  request.  The  following  command  will  NOT  work: 

uux  "aldiff  b!/usr/dan/xyz  c!/usr/dan/xyz  >  !xyz.difr' 

but  the  command 

uux  "aldiff  al/usr/dan/xyz  cl/usr/dan/xyz  >  Ixyz.difT' 
will  work  (if  diff  is  a  permitted  command). 

When  invoking  uux  from  csh(l),  the  !  character  must  be  prefixed  by  the  \  escape  to  inhibit  csh’s  history 
mechanism.  Quotes  are  not  sufficient. 
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BUGS 

Protected  files  and  files  that  are  in  protected  directories  that  are  owned  by  the  requestor  can  be  sent  in  com¬ 
mands  using  uux.  However,  if  the  requestor  is  root,  and  the  directory  is  not  searchable  by  “other”,  the 
request  will  fail. 
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NAME 

vacation  -  reply  to  mail  automatically 

SYNOPSIS 

vacation  [  -I  ] 

vacation  [  -j  ]  [  -a  alias  ]  [  -tN  ]  username 
DESCRIPTION 

vacation  automatically  replies  to  incoming  mail.  The  reply  is  contained  in  the  file  .vacation.msg  in  your 
home  directory.  The  vacation  program  run  interactively  will  create  a  .vacation.nisg  file  for  you  (which 
you  may  edit).  Type  vacation  with  no  arguments.  (See  USAGE  below.) 

For  example,  the  message  created  by  vacation  is: 

Subject:  away  from  my  mail 

From:  smith  (via  the  vacation  program) 

I  will  not  be  reading  my  mail  for  a  while. 

Your  mail  regarding  ”$SUBJECT"  will  be  read  when  I  return 

The  .vacation.msg  file  should  include  a  header  with  at  least  a  ‘Subject:’  line  (it  should  not  contain  a  ‘To:’ 
line  and  need  not  contain  a  ‘From:’  line,  since  these  are  generated  automatically). 

If  the  string  SSUBJECT  appears  in  the  .vacatiommsg  file,  it  is  replaced  with  the  subject  of  the  original  mes¬ 
sage  when  the  reply  is  sent. 

No  message  is  sent  if  the  ‘To:’  or  the  ‘Cc:’  line  does  not  list  the  user  to  whom  the  original  message  was 
sent  or  one  of  a  number  of  aliases  for  them,  if  the  initial  From  line  includes  the  string  -REQUEST!®,  or  if 
a  ‘Precedence:  bulk’  or  ‘Precedence:  junk’  line  is  included  in  the  header. 

OPTIONS 

-I  Initialize  the  .vacation.pag  and  .vacation.dir  files  and  start  vacation. 

If  the  -I  flag  is  not  specified,  and  a  user  argument  is  given,  vacation  reads  the  first  line  from  the  standard 
input  (for  a  ‘From:’  line,  no  colon).  If  absent,  it  produces  an  error  message.  The  following  options  may 
be  specified: 

—a  alias  Indicate  that  alias  is  one  of  the  valid  aliases  for  the  user  running  vacation,  so  that  mail  addressed 
to  that  alias  generates  a  reply. 

-j  Do  not  check  whether  the  recipient  appears  in  the  ‘To: ’  or  the  ‘Cc: ’  line. 

-tN  Change  the  interval  between  repeat  replies  to  the  same  sender.  The  default  is  1  week.  A  trailing 

s,  m,  h,  d,  or  w  scales  N  to  seconds,  minutes,  hours,  days,  or  weeks  respectively. 

USAGE 

To  start  vacation,  create  a  .forward  file  in  your  home  directory  containing  a  line  of  the  form: 

\usernamey  ”|/usr/ucb/vacation  username'^ 
where  username  is  your  login  name. 

Then  type  in  the  command: 
vacation  -I 

To  stop  vacation,  remove  the  .forward  file,  or  move  it  to  a  new  name. 
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If  vacation  is  run  with  no  arguments,  it  will  pemiit  you  to  interactively  turn  vacation  on  or  off.  It  will 
create  a  .vacation.msg  file  for  you,  or  edit  an  existing  one,  using  the  editor  specified  by  the  VISUAL  or  ED¬ 
ITOR  environment  variable,  or  vi(l)  if  neither  of  those  environment  variables  are  set.  If  a  .forward  file  is 
present  in  your  home  directory,  it  will  ask  whether  you  want  to  remove  it  and  turn  off  vacation.  If  it  is  not 
present  in  your  home  directory,  it  creates  it  for  you,  and  automatically  performs  a  ‘vacation  -I’  function, 
turning  on  vacation. 

FILES 

.forward 

$HOME/.vacation.nisg 

A  list  of  senders  is  kept  in  the  files  .vacation.pag  and  .vacation.dir  in  your  home  directory. 

SEE  ALSO 

vi(l),  sendmail(8) 
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NAME 

vfontinfo  -  inspect  and  print  out  information  about  fonts 
SYNOPSIS 

/usr/Iib/vfontinfo  [  -mvz  ]fontname  [  characters  ] 

AVAILABILITY 

This  command  is  available  with  the  Versatec  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

vfontinfo  allows  you  to  examine  a  font  in  the  UNIX  system  format  It  prints  out  all  the  information  in  the 
font  header  and  information  about  every  non-null  (width  >  0)  glyph.  This  can  be  used  to  make  sure  the 
font  is  consistent  with  the  format. 

ThQfontname  argument  is  the  name  of  the  font  you  wish  to  inspect.  It  writes  to  the  standard  output  If  it 
cannot  find  the  file  in  your  working  directory,  it  looks  in  /usr/lib/vfont  (the  place  most  of  the  fonts  are 
kept). 

The  characters,  if  given,  specify  certain  characters  to  show.  If  omitted,  the  entire  font  is  shown. 

OPTIONS 

-m  Display  header. 

“V  Verbose.  Display  bits  of  the  glyph  using  commas,  periods,  and  pipe  (T)  symbols. 

-z  Zoom.  Display  bits  of  the  glyph  as  an  array  of  M  and  SPACE  characters. 

FILES 

/usr/lib/vfont 

/usr/lib/vpd  Versatec  daemon 

SEE  ALSO 

vswap(l),  vwidth(l),  vfont(5) 
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NAME 

vgfind  -  grind  nice  program  listings 
SYNOPSIS 

ygrind  [  -ftitwWx  ]  [  -d  defs-file  ]  [  -h  header  ]  [  —llanguage  ]  [  sn  ]  [  -opagelist  ]  [  -Vprinter  ] 

[  ~T output-device  ]  filename. . . 

AVAILABILITY 

This  command  is  available  with  the  Text  software  installation  option.  Refer  to  Installing  SunOS  4.1  for  in¬ 
formation  on  how  to  install  optional  software, 

DESCRIPTION 

vgrind  formats  the  program  sources  named  by  the  filename  arguments  in  a  nice  style  using  troff(l).  Com¬ 
ments  are  placed  in  italics,  keywords  in  bold  face,  and  as  each  function  is  encountered  its  name  is  listed  on 
the  page  margin. 

vgrind  runs  in  two  basic  modes,  filter  mode  or  regular  mode.  In  filter  mode  vgrind  acts  as  a  filter  in  a 
manner  similar  to  tbl(l).  The  standard  input  is  passed  directly  to  the  standard  output  except  for  lines 
bracketed  by  the  trolT-like  macros: 

.vS  starts  processing 

•vE  ends  processing 

These  lines  are  formatted  as  described  above.  The  output  from  this  filter  can  be  passed  to  troff  for  output. 
There  need  be  no  particular  ordering  with  eqn(l)  or  tbi. 

In  regular  mode  vgrind  accepts  mpxii  filenames,  processes  them,  and  passes  them  to  troff  for  output.  If  no 
filename  is  given,  or  if  the  argument  is  given,  vgrind  reads  fi-om  the  standard  input  (default  if  -f  is 
specified). 

In  both  modes  vgrind  passes  any  lines  beginning  with  a  decimal  point  without  conversion. 

OPTIONS 

Note:  the  syntax  of  options  with  arguments  is  important.  Some  require  a  SPACE  between  the  option  name 
and  the  argument,  while  those  that  do  not  have  a  SPACE  below  will  not  tolerate  one. 

“f  Force  filter  mode. 

-n  Do  not  make  keywords  boldface. 

—x  Output  the  index  file  in  a  **pretty”  format.  The  index  file  itself  is  produced  whenever  vgrind  is  run 
with  a  file  called  index  present  in  the  current  directory.  The  index  of  function  definitions  can  then 
be  run  off  by  giving  vgrind  the  -x  option  and  the  file  index  as  argument. 

— w  Consider  TAB  characters  to  be  spaced  four  columns  apart  instead  of  the  usual  eight. 

-d  defs-file 

Specify  an  alternate  language  definitions  file  (default  is  /usr/Iib/vgrindefs). 

-h  header 

Specify  a  header  to  appear  in  the  center  of  every  output  page. 

-Manguage 

Specify  the  language  to  use.  Among  the  languages  cuirently  known  are:  Bourne  shell  (-Ish),  C 
(-Ic,  the  default),  C  shell  (-Icsh),  emacs  MLisp,  (-1ml),  FORTRAN  (-If),  Icon  (-11),  ISP  (-i),  LDL 
(-1LDL),  Model  (-Im),  Pascal  (-Ip),  and  RATFOR  (-Ir). 

-sn  Specify  a  point  size  to  use  on  output  (exactly  the  same  as  the  argument  of  a  troff  .ps  point  size  re¬ 
quest). 
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vgrind  passes  the  following  options  to  the  formatter  specified  by  the  TROFF  environment  variable,  see  EN¬ 
VIRONMENT  below. 

-t  Similar  to  the  same  option  in  troff;  that  is,  formatted  text  goes  to  the  standard  output 
-Qpagelist 

I»rint  only  those  pages  whose  page  numbers  appear  in  the  comma-separated  pagelist  of  numbers 
and  ranges,  A  range  N-M  means  pages  N  through  M\  an  initial  -N  means  from  the  beginning  to 
page  N;  and  a  final  N-  means  from  N  to  the  end. 

-Pprinter 

Send  output  to  the  named  printer. 

"T  output-device 

Format  output  for  the  specified  output-device . 

-W  Force  output  to  the  (wide)  Versatec  printer  rather  than  the  (narrow)  Varian.  vtrofT(l)  only. 
ENVIRONMENT 

In  regular  mode  vgrind  feeds  its  intermediate  output  to  the  text  formatter  given  by  the  value  of  the  TROFF 
environment  variable,  or  to  troff  if  this  variable  is  not  defined  in  the  environment.  This  mechanism  allows 
for  local  variations  in  troff ’s  name. 


FILES 

index 

/usr/lib/vgrindefs 
/  usr/lib/ vfontedpr 
/  usr/share/lib/tmac/tmac.  vgrind 


file  where  source  for  index  is  created 
language  descriptions 
preprocessor 
macro  package 


SEE  ALSO 

troff(l),  vtroff(l),  vgrindefs(5) 


BUGS 

vgrind  assumes  that  a  certain  programming  style  is  followed: 

C  Function  names  can  be  preceded  on  a  line  only  by  SPACE,  TAB,  or  an  asterisk.  The 

parenthesized  arguments  must  also  be  on  the  same  line. 


FORTRAN  Function  names  need  to  appear  on  the  same  line  as  the  keywords or  subroutine. 

MLisp  Function  names  should  not  appear  on  the  same  line  as  the  preceding  defun . 

Model  Function  names  need  to  appear  on  the  same  line  as  the  keywords  is  heginproc. 

Pascal  Function  names  need  to  appear  on  the  same  line  as  the  keywords /wncfton  or  procedure . 

If  these  conventions  are  not  followed,  the  indexing  and  marginal  function  name  comment  mechanisms  will 
fail. 


More  generally,  arbitrary  formatting  styles  for  programs  mostly  look  bad.  The  use  of  SPACE  characters  to 
align  source  code  fails  miserably;  if  you  plan  to  vgrind  your  program  you  should  use  TAB  characters.  This 
is  somewhat  inevitable  since  the  fonts  vgrind  uses  are  variable  width. 

The  mechanism  of  ctags(l)  in  recognizing  functions  should  be  used  here. 

The  -w  option  is  a  crock,  but  there  is  no  other  way  to  achieve  the  desired  effect. 
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The  macros  defined  in  tmac.vgrind  do  not  coexist  gracefully  with  those  of  other  macro  packages,  making 
filter  mode  difficult  to  use  effectively. 

vgrind  does  not  process  certain  special  ch^cters  in  csh(l)  scripts  correctly. 
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NAME 

vi,  view,  vedit  -  visual  display  editor  based  on  ex(l) 

SYNOPSIS 

vi  [  -CILRVx  ]  [  -c  command  ]  [  -r  filename  ][~ttag]l  -wnnn  ]  [  -^-command  ]  filename, . . 

view. . . 
vedit. . . 

DESCRIPTION 

vi  (visual)  is  a  display  oriented  text  editor  based  on  ex(l).  ex  and  vi  are,  in  fact,  the  same  text  editor;  it  is 
possible  to  get  to  the  command  mode  of  ex  from  within  vi  and  vice-versa. 

view  runs  vi  with  the  readonly  flag  set.  With  view,  you  can  browse  through  files  interactively  without 
making  any  changes. 

vedit  runs  vi  with  the  report  flag  set  to  1,  the  showmode  and  novice  flags  set,  and  the  magic  flag  turned 
off.  These  default  settings  are  intended  to  make  easier  for  beginners  to  learn  vi. 

OPTIONS 
-C 


-1 

~L 

_R 

-V 

-X 


-c  command 

-T  filename 
-ttag 

^command 
ENVIRONMENT 

The  editor  recognizes  the  environment  variable  EXINIT  as  a  command  (or  list  of  commands  separated  by  | 
characters)  to  run  when  it  starts  up.  If  this  variable  is  undefined,  the  editor  checks  for  startup  commands  in 
the  file  7.exrc  file,  which  you  must  own.  However,  if  there  is  a  .exrc  owned  by  you  in  the  current  directo¬ 
ry,  the  editor  takes  its  startup  commands  from  this  file  —  overriding  both  the  file  in  your  home  directory 
and  the  environment  variable. 


Encryption  option;  the  same  as  the  -x  option,  except  that  all  input  text  is  assumed  to  have 
already  been  encrypted.  This  guarantees  decryption  in  the  cases  where  the  -x  option  in¬ 
correctly  determines  that  the  input  file  is  not  already  encrypted  (this  is  extremely  rare,  and 
will  only  occur  in  conjunction  with  the  use  of  files  containing  non- ASCII  text). 

Set  up  for  editing  LISP  programs. 

List  the  names  of  all  files  saved  as  the  result  of  an  editor  or  system  crash. 

Edit  files  in  read  only  state.  This  has  the  same  effect  as  the  view  command. 

Verbose.  Any  non-tty  input  will  be  echoed  on  standard  error. 

Prompt  for  a  key  to  be  used  in  encrypting  the  file  being  edited.  When  used  in  conjunction 
with  a  pre-existing  file,  ex  will  make  an  educated  guess  to  determine  whether  or  not  the  in¬ 
put  text  file  is  already  encrypted. 

Start  the  editing  session  by  executing  the  editor  command  command.  If  command  contains 
spaces,  it  must  be  surrounded  by  double  quotess,  see  EXAMPLES  below. 

Recover  the  named  files  after  a  crash. 

Edit  the  file  containing  tag.  There  must  be  a  tags  database  in  the  directory,  built  by 
ctags(l),  that  contains  a  reference  to  tag. 

Start  the  editing  session  by  executing  command.  This  is  identical  to  the  -c  option. 
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The  environment  variables  LC_CTYPE,  LANG,  and  LC^default  control  the  character  classification 
throughout  vi.  On  entry  to  vi,  these  environment  variables  are  checked  in  the  following  order:  LC  CTYPE, 
LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for  character 
classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current  valid  charac¬ 
ter  classification  rules  of  LC^CTYPE.  When  none  of  the  values  is  valid,  the  shell  character  classification 
defaults  to  the  POSIX.l  “C”  locale.  In  the  “C”  locale,  all  8-bit  characters  are  escaped  into  an  octal  represen¬ 
tation. 

EXAMPLES 

The  following  command: 

example  %  vi  -c  ":r  test"  tested 

will  read  in  the  file  test  at  the  end  of  the  tested  file. 

SEE  ALSO 

ctags(l),  ex(l) 

Editing  Text  Files 

SunOS  User’s  Guide:  Getting  Started 

BUGS 

Software  TAB  characters  using  CTRL-T  work  only  immediately  after  the  autoindent. 

SHIFT-left  and  SHIFT-right  on  intelligent  terminals  do  not  make  use  of  insert  and  delete  character  opera¬ 
tions  in  the  terminal. 

The  wrapmargin  option  can  be  fooled  since  it  looks  at  output  columns  when  blanks  are  typed.  When  in¬ 
sert  mode  pushes  an  existing  word  through  the  margin  and  onto  the  next  line  without  a  break,  the  line  will 
not  be  broken. 

Insert/delete  within  a  line  can  be  slow  if  TAB  characters  are  present  on  intelligent  terminals,  since  the  ter¬ 
minals  need  help  in  doing  this  correctly. 

Saving  text  on  deletes  in  the  named  buffers  is  somewhat  inefficient. 

The  source  command  does  not  work  when  executed  as  ‘:source’;  there  is  no  way  to  use  the  ‘:append’, 
‘:change’,  and  ‘:insert’  commands,  since  it  is  not  possible  to  give  more  than  one  line  of  input  to  a  ‘f  es¬ 
cape.  To  use  these  on  a  ‘rglobaP  you  must  Q  to  ex  command  mode,  execute  them,  and  then  reenter  the 
screen  editor  with  vi  or  open. 

When  using  the  -r  option  to  recover  a  file,  you  must  write  the  recovered  text  before  quitting  or  you  will 
lose  it.  vi  does  not  prevent  you  from  exiting  without  writing  unless  you  make  changes. 

vi  does  not  adjust  when  the  SunView  window  in  which  it  runs  is  resized. 

RESTRICTIONS 

The  encryption  facilities  of  vi  are  not  available  on  software  shipped  outside  the  U.S. 
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NAME 

vplot  -  plot  graphics  for  a  Versatec  printer 
SYNOPSIS 

vplot  [  -VW  ]  [  -b  lpr~argument  ]  filename 
AVAILABILITY 

This  command  is  available  with  the  Versatec  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software, 

DESCRIPTION 

vplot  reads  plot(5)  format  graphics  input  from  the  file  specified  by  filename  (the  standard  input  if  no 
filename  is  specified)  and  produces  a  plot  on  the  Varian  or  Versatec  printer. 

OPTIONS 

-V  Force  output  to  the  standard  Versatec  printer. 

-W  Force  output  to  the  (wide)  Versatec  printer  rather  than  the  standard  Versatec  printer. 

-b  Ipr-argument 

argument  (the  next  argument  on  the  command  line)  specifies  extra  arguments  to  Ipr(l). 

SEE  ALSO 

Ipr(l),  plot(lG),plot(5) 
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NAME 

vswap  -  convert  a  foreign  font  file 

SYNOPSIS 

/usr/lib/ vswap  [  -r  ] 

AVAILABILITY 

This  command  is  available  with  the  Versatec  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCHUPTION 

Without  the  -r  option,  vswap  translates  its  standard  input  (which  must  be  a  vfont(5)  file  in  the  reversed- 
byte  order)  into  a  locally  correct  vfont  file  on  its  standard  output.  With  the  -r  option,  vswap  translates  its 
standard  input  (which  must  be  a  vfont  file  in  the  local-byte  order)  into  a  byte-reversed  vfont  file  on  its  stan¬ 
dard  output 

The  UNIX  system  vfont  representation  for  fonts  is  a  binary  file  containing  machine-dependent  elements  — 
short  (16-bit)  integers,  in  particular.  There  are  (at  least)  two  common  ways  of  representing  a  16-bit  integer. 
A  program  compiled  on  a  VAX  will  expect  the  VAX  format,  while  the  same  program  compiled  on  a 
machine  using  a  Motorola  68000-family  processor  or  a  SPARC  processor  will  expect  the  reverse  format 
vswap  can  be  used  to  convert  font  files  created  on  a  VAX  to  the  format  required  to  use  them  on  Suns.  (All 
Suns  use  the  same  vfont  format,  regardless  of  the  native  byte  order  of  the  processor,  including  Suns  that 
use  the  Intel  80386  processor.  Programs  that  will  be  run  on  Suns  that  use  the  Intel  80386  processor  must 
be  aware  of  this,  and  convert  the  machine-dependent  elements  when  they  read  or  write  vfont  files.)  It  can 
also  convert  Sun-format  font  files  to  VAX  format  (with  the  -r  option). 

SEE  ALSO 

troff(l),  vfont(5) 

BUGS 

A  machine-independent  font  format  should  be  defined. 
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NAME 

vtroff  -  troff  to  a  raster  plotter 
SYNOPSIS 

vtroff  [  -wx  ]  [  -F  majorfont  ]  [  -Mength  ]  [  -123  minorfont  ]  trojf-argwnents 

AVAILABILITY 

This  command  is  available  with  the  Versatec  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  instalhoptional  software. 

DESCRIPTION 

vtroff  runs  troff(l)  sending  its  output  through  various  programs  to  produce  typeset  output  on  a  raster 
plotter  such  as  a  Benson-Varian  or  a  Versatec. 

OPTIONS 

-w  Specify  that  a  wide  output  device  be  used;  the  default  is  to  use  a  narrow  device. 

-X  Simulate  photo-typesetter  output  exactly.  As  with,  using  the  width  tables  for  the  C.A.T.  photo¬ 

typesetter. 

“F  fontname 

Specify  fontname  as  the  desired  font.  This  will  place  normal,  italic  and  bold  versions  of  the  font 
on  positions  1, 2,  and  3.  The  default  font  is  a  Hershey  font,  argument  and  then  the  font  name. 

-Mength 

Split  the  output  onto  successive  pages  every  length  inches  rather  than  the  default  1 1  inches. 

-123  minorfont 

Place  a  font  only  on  a  single  position  specified  by  -n  (where  n  is  1,  2,  or  3)  and  the  minor  font 
name.  A  .r  will  be  added  to  the  minor  font  name  if  needed.  Thus 
vtroff  -ms  paper 

will  set  a  paper  in  the  Hershey  font,  while 
vtroff  -F  nonie  -ms  paper 

will  set  the  paper  in  the  (sans  serif)  nonie  font. 

FILES 

/usr/share/lib/tmac/tmac.vcat 

default  font  mounts  and  bug  fixes 
/usr/lib/fontinfo/*  fixes  for  other  fonts 

/usr/lib/vfont  directory  containing  fonts 

SEE  ALSO 

troff(l),  vfont(5) 

BUGS 

Since  some  macro  packages  work  correctly  only  if  the  fonts  named  R,  I,  B,  and  S  are  mounted,  and  since 
the  Versatec  fonts  have  different  widths  for  individual  characters  than  the  fonts  found  on  the  typesetter,  the 
following  dodge  was  necessary:  If  you  do  not  use  the  .fp  troff  directive  then  you  get  the  widths  of  the  stan¬ 
dard  typesetter  fonts  suitable  for  shipping  the  output  of  troff  over  the  network  to  the  computer  center  A 
machine  for  phototypesetting.  If,  however,  you  remount  the  R,  I,  B  and  S  fonts,  then  you  get  the  width 
tables  for  the  Versatec. 
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NAME 

vwidth  -  make  a  troff  width  table  for  a  font 
SYNOPSIS 

/usr/lib/vwidth  fontfile  pointsize  >  ftxxx 
cc  -c  ftcx.c 

mv  ftcc.o  /usr/lib/font/fta; 

AVAILABILITY 

This  command  is  available  with  the  Versatec  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

vwidth  translates  from  the  width  information  stored  in  the  vfont  style  format  to  the  format  expected  by 
trolT(l)  —  an  object  file  in  a.out(5)  format,  troff  should  look  directly  in  the  font  file  but  it  doesn’t. 

vwidth  should  be  used  after  editing  a  font  with  fontedit(l).  It  is  not  necessary  to  use  vwidth  unless  you 
have  made  a  change  that  would  affect  the  width  tables.  Such  changes  include  numerically  editing  the 
width  field,  adding  a  new  character,  and  moving  or  copying  a  character  to  a  new  position.  It  is  not  always 
necessary  to  use  vwidth  if  the  physical  width  of  the  glyph  (for  instance  the  number  of  columns  in  the  bit 
matrix)  has  changed,  but  if  it  has  changed  much  the  logical  width  should  probably  be  changed  and  vwidth 
run. 

vwidth  produces  a  C  program  on  its  standard  output.  This  program  should  be  run  through  the  C  compiler 
and  the  object  (that  is,  the  .o  file)  saved.  The  resulting  file  should  be  placed  in  /usr/lib/font  in  the  file  fta 
where  xx  is  a  one  or  two  letter  code  that  is  the  logical  (internal  to  troff)  font  name.  This  name  can  be 
found  by  looking  in  the  file  /usr/lib/fontinfo//)iam£=t‘  where/flom^  is  the  external  name  of  the  font. 

FILES 

/usr/lib/font 

a.out 

SEE  ALSO 

troff(l),  vtroff(l),  fontedit(l),  a.out(5),  vfont(5) 
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NAME 

w  ~  who  is  logged  in,  and  what  are  they  doing 

SYNOPSIS 

w  [  -his  ]  [  user  ] 

DESCRIPTION 

w  displays  a  summary  of  the  current  activity  on  the  system,  including  what  each  user  is  doing.  The  head¬ 
ing  line  shows  the  current  time  of  day,  how  long  the  system  has  been  up,  the  number  of  users  logged  into 
the  system,  and  the  load  averages.  The  load  average  numbers  give  the  number  of  jobs  in  the  run  queue 
averaged  over  1,  5  and  15  minutes. 

The  fields  displayed  are:  the  users  login  name,  the  name  of  the  tty  the  user  is  on,  the  time  of  day  the  user 
loSS^d  on  (in  hours. minutes),  the  idle  dme  —  that  is,  the  number  of  minutes  since  the  user  last  typed  any¬ 
thing  (in  hoursiminutes),  the  CPU  time  used  by  all  processes  and  their  children  on  that  terminal  (in 
minutes: seconds),  the  CPU  time  used  by  the  currently  active  processes  (in  minutes:seconds),  the  name  and 
arguments  of  the  current  process. 

If  a  user  name  is  included,  output  is  restricted  to  that  user. 

OPTIONS 

-h  Suppress  the  heading. 

~l  Produce  a  long  form  of  output,  which  is  the  default. 

-s  Produce  a  short  form  of  output.  In  the  short  form,  the  tty  is  abbreviated,  the  login  time  and  CPU 

times  are  left  off,  as  are  the  arguments  to  commands. 

EXAMPLE 

example  %  w 

7:36am  up  6  days,  16:45,  1  users,  load  average;  0.20, 0.23,  0.18 
User  tty  login@  idle  JCPU  PCPU  what 

ralph  console  7:10am  1  10:05  4:31  w 

example  % 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  w.  On  entry  to  w,  these  environment  variables  are  checked  in  the  following  order:  LC  CTYPE, 
LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for  character 
classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current  valid  charac¬ 
ter  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character  classification 
defaults  to  the  POSIX.1  “C”  locale. 

FILES 

/etc/utmp 

/dev/kmem 

/dev/drum 

SEE  ALSO 

ps(l),  who(l),  utmp(5V) 

BUGS 

The  notion  of  the  “current  process”  is  muddy.  The  current  algorithm  is  ‘the  highest  numbered  process  on 
the  terminal  that  is  not  ignoring  interrupts,  or,  if  there  is  none,  the  highest  numbered  process  on  the  termi¬ 
nal*.  This  fails,  for  example,  in  critical  sections  of  programs  like  the  shell  and  editor,  or  when  faulty  pro¬ 
grams  running  in  the  background  fork  and  fail  to  ignore  interrupts.  In  cases  where  no  process  can  be 
found,  w  prints 
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The  CPU  time  is  only  an  estimate,  in  particular,  if  someone  leaves  a  background  process  running  after  log¬ 
ging  out,  the  person  currently  on  that  terminal  is  “charged”  with  the  time. 

Background  processes  are  not  shown,  even  though  they  account  for  much  of  the  load  on  the  system. 

Sometimes  processes,  typically  those  in  the  background,  are  printed  with  null  or  garbaged  arguments.  In 
these  cases,  the  name  of  the  command  is  printed  in  parentheses. 

w  does  not  know  about  the  new  conventions  for  detecting  background  jobs.  It  will  sometimes  find  a  back¬ 
ground  job  instead  of  the  right  one. 
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NAME 

wait  -  wait  for  a  process  to  finish 

SYNOPSIS 

wait 

DESCRIPTION 

Wait  until  all  processes  started  with  &  or  bg  have  completed,  and  report  on  abnormal  terminations. 

Because  the  wait(2V)  system  call  must  be  executed  in  the  parent  process,  the  shell  itself  executes  wait, 
without  creating  a  new  process. 

SEE  ALSO 

csh(l),  sh(l),  wait(2V) 

BUGS 

Not  all  the  processes  of  a  3-  or  more-stage  pipeline  are  children  of  the  shell,  and  thus  cannot  be  waited  for. 
This  bug  does  not  apply  to  csh(l). 
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NAME 

wall  ”  write  to  all  users  logged  in 
SYNOPSIS 

wall  [  -a  ]  [filename  ] 

DESCRIPTION 

wall  reads  the  standard  input  until  an  EOF.  It  then  sends  this  message,  preceded  by  ‘Broadcast  Message 
4./,  to  all  logged  in  users.  If  filename  is  given,  then  the  message  is  read  in  from  that  file.  Normally, 
pseudo-terminals  that  do  not  correspond  to  rlogin  sessions  are  ignored.  Thus  when  in  sunview(l),  the  mes¬ 
sage  appears  only  on  the  console  window.  However,  ~a  will  send  the  message  even  to  such  pseudo¬ 
terminals. 

The  sender  should  be  super-user  to  override  any  protections  the  users  may  have  invoked. 

FILES 

/dev/tty? 

/etc/utmp 

SEE  ALSO 

mesg(l),  sunview(l),  write(l) 
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NAME 

wc  -  display  a  count  of  lines,  words  and  characters 
SYNOPSIS 

wc  [  -Iwc  ]  [filename  . . ,  ] 

DESCRIPTION 

wc  counts  lines,  words,  and  characters  in  filenames,  or  in  the  standard  input  if  no  filename  appears.  It  also 
keeps  a  total  count  for  all  named  files.  A  word  is  a  string  of  characters  delimited  by  SPACE,  TAB,  or  NEW- 
LINE  characters. 

OPTIONS 

filenames  are  specified  on  the  command  line,  their  names  will  be  printed  along  with  the  counts. 

The  default  is  -Iwc  (count  lines,  words,  and  characters). 

I  Count  lines, 

w  Count  words, 

c  Count  characters. 

EXAMPLE 

example  % 

wc/usr/share/man/manl/{csh.l,sh.l,telnet.l} 


1876 

11223 

65895 

/usr/share/man/manl/csh.l 

674 

3310 

20338 

/usr/share/maii/manl/sh.l 

260 

1110 

6834 

/usr/share/man/manl/telnet.l 

2810 
example  % 

15643 

93067 

total 

ENVIRONMENT 

The  environment  variables  LC_^CTYPE,  LANG,  and  LC_defauIt  control  the  character  classification 
throughout  wc.  On  entry  to  wc,  these  environment  variables  are  checked  in  the  following  order: 
^^™^TYPE,  LANG,  and  LC_default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  cuirent 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  “C”  locale. 
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NAME 

what  -  extract  SCCS  version  information  from  a  file 
SYNOPSIS 

what  [  -s  ]  filename  . . . 

DESCRIPTION 

what  searches  each  filename  for  occurrences  of  the  pattern  (5)(#)  that  the  SCCS  get  command  (see  sccs- 
get(l))  substitutes  for  the  %Z%  ID  keyword,  and  prints  what  follows  up  to  a  NEWLINE,  \,  or  null 
character.  For  instance,  if  the  C  program  in  file  programs  contains 

char  sccsid[  ]  =  ”  @(#)identification  information  " ; 

and  program.c  is  compiled  to  yield  program.o  and  a,out,  the  command; 
what  program.c  program.o  a.out 

produces: 

program.c: 

identification  information 
program.o: 

identification  information 
a.out:  identification  information 

OPTIONS 

-s  Stop  after  the  first  occurrence  of  the  pattern. 

SEE  ALSO 

sccs(l),  s€cs-admin(l),  sccs-cdc(l),  sccs-comb(l),  sccs-delta(l),  sccs-get(l),  sccs-help(l),  sccs-prs(l), 
sccs-prt(l),  sccs-rmdel(l),  sccs-sact(l),  sccs"sccsdiff(l),  sccs-unget(l),  sccs-val(l),  sccsfile(5) 

Programming  Utilities  and  Libraries 

DIAGNOSTICS 

Use  the  SCCS  help  command  for  explanations  (see  sccs-help(l)). 

BUGS 

There  is  a  remote  possibility  that  a  spurious  occurrence  of  the  ‘@(#)’  pattern  could  be  found  by  what. 
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NAME 


whatis  -  display  a  one-line  summary  about  a  keyword 


SYNOPSIS 

whatis  command. . , 


DESCRIPTION 

whatis  looks  up  a  given  command  and  displays  the  header  line  from  the  manual  section.  You  can  then  run 
the  iiian(l)  command  to  get  more  information.  If  the  line  starts  'nameisection) . . you  can  do 
‘man  section  name’  to  get  the  documentation  for  it.  Try  ‘whatis  ed’  and  then  you  should  do 
‘man  1  ed’  to  get  the  manual  page  for  ed(l). 

whatis  is  actually  just  the  -f  option  to  the  man(l)  command. 

whatis  uses  the  whatis  database.  This  database  can  be  created  using  the  -w  option  of  catman(8). 

FILES 

/usr/[share]/man/whatis 

database 


SEE  ALSO 

apropos(l),  man(l),  catman(8) 

NOTES 

whatis  uses  the  /usr/man/whatis  database,  which  is  created  by  catman(8). 
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NAME 

whereis  —  locate  the  binary,  source,  and  manual  page  files  for  a  command 
SYNOPSIS 

whereis  [  “bmsu  ]  [ -BMS  directory. . .  -f] filename  . . . 

DESCRIPTION 

whereis  locates  source/binary  and  manuals  sections  for  specified  files.  The  supplied  names  are  first 
stripped  of  leading  pathname  components  and  any  (single)  trailing  extension  of  the  form  .ext,  for  example, 
.c.  Prefixes  of  s.  resulting  from  use  of  source  code  control  are  also  dealt  with,  whereis  then  attempts  to 
locate  the  desired  program  in  a  list  of  standard  places: 


/usr/bin 

/usr/bin 

/usr/5bin 

/usr/games 

/usr/hosts 

/usr/include 

/usr/local 

/usr/etc 

/usr/lib 

/usr/share/man 

/usr/src 

/usr/ucb 

OPTIONS 

-b  Search  only  for  binaries. 

-m  Search  only  for  manual  sections. 

-s  Search  only  for  sources. 

-u  Search  for  unusual  entries.  A  file  is  said  to  be  unusual  if  it  does  not  have  one  entry  of  each 

requested  type.  Thus  ‘whereis  -m  ~u  *’  asks  for  those  files  in  the  current  directory  which  have 
no  documentation. 

-B  Change  or  otherwise  limit  the  places  where  whereis  searches  for  binaries. 

-M  Change  or  otherwise  limit  the  places  where  whereis  searches  for  manual  sections. 

“S  Change  or  otherwise  limit  the  places  where  whereis  searches  for  sources. 

-f  Terminate  the  last  directory  list  and  signals  the  start  of  file  names,  and  must  be  used  when  any  of 

the  — B,  — M,  or  -S  options  are  used. 

EXAMPLE 

Find  all  files  in  /usr/bin  which  are  not  documented  in  /usr/share/man/manl  with  source  in  /usr/src/cmd: 
example  %  cd  /usr/ucb 

example%  whereis  ~u  -M  /usr/share/man/manl  -S  /usr/src/cmd  -f  * 

FILES 

/usr/src/* 

/usr/{doc,man}/* 

/etc,  /usr/ {lib, bin, ucb, old, new, local} 

SEE  ALSO 

chdir(2V) 
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BUGS 

Since  whereis  uses  chdir(2V)  to  run  faster,  pathnames  given  with  the  -M,  -S,  or  -B  must  be  full;  that  is, 
they  must  begin  with  a  7’. 
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NAME 

which  -  locate  a  command;  display  its  pathname  or  alias 

SYNOPSIS 

which  [filename  ] . . . 

DESCRIPTION 

which  takes  a  list  of  names  and  looks  for  the  files  which  would  be  executed  had  these  names  been  given  as 
commands.  Each  argument  is  expanded  if  it  is  aliased,  and  searched  for  along  the  user’s  path.  Both  aliases 
and  path  are  taken  from  the  user’s  .cshrc  file. 

FILES 

7.cshrc  source  of  aliases  and  path  values 

SEE  ALSO 

csh(l) 

DIAGNOSTICS 

A  diagnostic  is  given  for  names  which  are  aliased  to  more  than  a  single  word,  or  if  an  executable  file  with 
the  argument  name  was  not  found  in  the  path. 

BUGS 

Only  aliases  and  paths  from  7.cshrc  are  used;  importing  from  the  current  environment  is  not  attempted. 
Must  be  executed  by  csh(l),  since  only  csh  knows  about  aliases. 

To  compensate  for  7,cshrc  files  in  which  aliases  depend  upon  the  prompt  variable  being  set,  which  sets 
this  variable.  If  the  ”/.cshrc  produces  output  or  prompts  for  input  when  prompt  is  set,  which  may  produce 
some  strange  results. 
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NAME 

who  -  who  is  logged  in  on  the  system 
SYNOPSIS 

who  [  who-file  ]  [  am  i  ] 

DESCRIPTION 

Used  without  arguments,  who  lists  the  login  name,  terminal  name,  and  login  time  for  each  current  user, 
who  gets  this  information  from  the  /etc/utmp  file. 

If  a  filename  argument  is  given,  the  named  file  is  examined  instead  of /etc/utmp.  Typically  the  named  file 
is  /var/adm/wtmp,  which  contains  a  record  of  all  logins  since  it  was  created.  In  this  case,  who  lists  logins, 
logouts,  and  crashes.  Each  login  is  listed  with  user  name,  terminal  name  (with  /dev/  suppressed),  and  date 
and  time.  Logouts  produce  a  similar  line  without  a  user  name.  Reboots  produce  a  line  with  in  place  of 
the  device  name,  and  a  fossil  time  indicating  when  the  system  went  down.  Finally,  the  adjacent  pair  of  en¬ 
tries  ‘I’  and  *}’  indicate  the  system-maintained  time  just  before  and  after  a  date  command  changed  the 
system’s  idea  of  the  time. 

With  two  arguments,  as  in  ‘who  am  i’  (and  also  ‘who  is  who’),  who  tells  who  you  are  logged  in  as:  it 
displays  your  hostname,  login  name,  terminal  name,  and  login  time. 

EXAMPLES 

example  %  who  am  i 
examplelralph  ttypO  Apr  27  11:24 
example  % 

example  %  who 
mktg  ttymO  Apr  27  11:11 

gwen  ttypO  Apr  27  11:25 

ralph  ttypl  Apr  27  11:30 

example  % 

FILES 

/etc/utmp 

/var/adm/wtmp 

SEE  ALSO 

login(l),  w(l),  whoami(l),  utmp(5V),  locale(5) 
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NAME 

whoami  -  display  the  effective  current  username 

SYNOPSIS 

whoami 

DESCRIPTION 

whoami  displays  the  login  name  corresponding  to  the  current  effective  uer  ID.  If  you  have  used  su(lV)  to 
temporarily  adopt  another  user,  whoami  will  report  the  login  name  associated  with  that  user  ID.  whoami 
gets  its  information  from  the  geteuidO  and  getpwuid()  library  routines  (see  getuid(2V)  and  getpwent(3V), 
respectively). 

FILES 

/etc/passwd  username  data  base 

/etc/utmp  database  of  users  currently  logged  in 

SEE  ALSO 

su(lV),  who(l),  getuid(2VX  getpwent(3V),  utmp(5V) 
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NAME 

whois  -  TCP/TP  Internet  user  name  directory  service 
SYNOPSIS 

whois  [  -h  host  ]  identifier 
DESCRIPTION 

whois  searches  for  an  TCP/IP  directory  entry  for  an  identifier  which  is  either  a  name  (such  as  “Smith”)  or  a 
handle  (such  as  “SRI-NIC”).  You  can  force  a  name-only  search  by  preceding  the  name  with  a  period;  you 
can  force  a  handle-only  search  by  preceding  the  handle  with  an  exclamation  point.  See  EXAMPLES. 

If  you  are  searching  for  a  group  or  organization  entry,  you  can  have  the  entire  membership  list  of  the  group 
displayed  with  the  record  by  preceding  the  argument  with  **’  (an  asterisk). 

You  may  of  course  use  an  exclamation  point  and  asterisk,  or  a  period  and  asterisk  together. 

EXAMPLES 

example  %  whois  Smith 
looks  for  name  or  handle  SMITH. 

example%  whois  \!SRI-NIC 
looks  for  handle  SRI-NIC  only. 

example  %  whois  ’.Smithy  John’ 
looks  for  name  “John  Smith”  only. 

Adding  to  the  name  or  handle  argument  will  match  anything  from  that  point;  that  is,  ‘ZU. ..’  will 
match  ZUL,  ZUM,  etc. 
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NAME 

write  -  write  a  message  to  another  user 
SYNOPSIS 

write  username  [  ttyname  ] 

DESCRIPTION 

write  copies  lines  from  your  standard  input  to  username's  screen. 

When  you  type  a  write  command,  the  person  you  are  writing  to  sees  a  message  like  this: 

Message  from  hostnamelyourname  on  yourttyname 

After  typing  the  write  command,  enter  the  text  of  your  message.  What  you  type  appears  line-by-line  on 
the  other  user’s  screen.  Conclude  by  typing  an  EOF  indication  (CTRUD)  or  an  interrupt.  At  this  point 
write  displays  EOF  on  your  recipient’s  screen  and  exits. 

To  write  to  a  user  who  is  logged  in  more  than  once,  use  the  ttyname  argument  to  indicate  the  appropriate 
terminal  name. 

You  can  grant  or  deny  other  users  permission  to  write  to  you  by  using  the  mesg  command  (default  allows 
writing).  Certain  commands,  nroff(l)  and  pr(l V)  in  particular,  do  not  allow  anyone  to  write  to  you  while 
you  are  using  them  in  order  to  prevent  messy  output. 

If  write  finds  the  character  ‘1’  at  the  beginning  of  a  line,  it  calls  the  shell  to  execute  the  rest  of  the  line  as  a 
command. 

Two  people  can  carry  on  a  conversation  by  “writing”  to  each  other.  When  the  other  person  receives  the 
message  indicadng  you  are  writing  to  him,  he  can  then  write  back  to  you  if  he  wishes.  However,  since  you 
are  now  simultaneously  typing  and  receiving  messages,  you  end  up  with  garbage  on  your  screen  unless  you 
work  out  some  sort  of  scheduling  scheme  with  your  partner.  You  might  try  the  following  conventional 
protocol:  when  you  first  write  to  another  user,  wait  for  him  to  write  back  before  starting  to  send.  Each  per¬ 
son  should  end  each  message  with  a  distinctive  signal - o-  (for  “over”)  is  standard  —  so  that  the  other 

knows  when  to  begin  a  reply.  To  end  your  conversation,  type  -oo-  (for  “over  and  out”)  before  finishing  the 
conversation. 

EXAMPLE 

Here  is  an  example  of  a  short  dialog  between  two  people  on  different  terminals.  Two  users  called 
“Horace”  and  “Eudora”  are  logged  in  on  a  system  called  “jones”.  To  illustrate  the  process,  both  users’ 
screens  are  shown  side-by-side: 

Eudora’s  Terminal  Horace’s  Terminal 

Horace  is  staring  at  his  screen 

jones  %  write  horace 

how  about  a  squash  game  tonight?  -o- 

Message  from  jonesleudora  on  tty09  at  17:05 . . . 
how  about  a  squash  game  tonight?  -o- 
jones%  write  eudora 
I’m  playing  tiddlywinks  with  Carmeline  -o- 
Message  from  jones! horace  on  tty03  at  17:06  . . . 

I’m  playing  tiddlywinks  with  Carmeline  -o- 
How  about  the  beach  on  Sunday?  -o- 

How  about  the  beach  on  Sunday?  -o- 
Sorry,  I’m  washing  my  tent  that  day  -o- 

Sorry,  I’m  washing  my  tent  that  day  -o- 
See  you  when  I  get  back  from  Peru  -oo- 
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See  you  when  I  get  back  from  Peru  -oo- 
D 

jones%  EOF 

1  hear  rack  of  llama  is  very  tasty  -oo- 
‘D 

I  hear  rack  of  llama  is  very  tasty  -oo- 

EOF  jones% 

ENVIRONMENT 

The  environment  variables  LC_CTYPE,  LANG,  and  LC_default  control  the  character  classification 
throughout  write.  On  entry  to  write,  these  environment  variables  are  checked  in  the  following  order: 
LC_CTYPE,  LANG,  and  LC^default.  When  a  valid  value  is  found,  remaining  environment  variables  for 
character  classification  are  ignored.  For  example,  a  new  setting  for  LANG  does  not  override  the  current 
valid  character  classification  rules  of  LC_CTYPE.  When  none  of  the  values  is  valid,  the  shell  character 
classification  defaults  to  the  POSIX.l  “C”  locale. 

FILES 

/etc/utmp  to  find  user 

/usr/bin/sh  to  execute  I 

SEE  ALSO 

mail(l),  mesg(l),  pr(lV),  talk(l),  troff(l),  who(l),  locale(5) 
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NAME 

xargs  -  construct  the  arguments  list(s)  and  execute  a  command 

SYNOPSIS 

xargs  [  -ptx  ]  [  -eeqfstr  ]  [  -ireplstr  ]  [  ~\number  ]  [  -nnumber  ]  [  -ssize  ] 

[  command  linitiaUarguments  ]  ] 

AVAILABILITY 

This  command  is  available  with  the  System  V  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

xargs  combines  the  fixed  initial-arguments  with  arguments  read  from  the  standard  input,  to  execute  the 
specified  command  one  or  more  times.  The  number  of  arguments  read  for  each  command  invocation,  and 
the  manner  in  which  they  are  combined  are  determined  by  the  options  specified. 

command,  which  may  be  a  shell  file,  is  searched  for  using  one’s  $PATH.  If  command  is  omitted, 
/usr/bin/echo  is  used. 

Arguments  read  in  from  the  standard  input  are  defined  to  be  contiguous  strings  of  characters  delimited  by 
white  space.  Empty  lines  are  always  discarded.  Blanks  and  tabs  may  be  embedded  as  part  of  an  argument 
if  they  are  escaped  or  quoted.  Characters  enclosed  in  quotes  (single  or  double)  are  taken  literally,  and  the 
delimiting  quotes  are  removed.  Outside  of  quoted  strings,  a  *\’  (backslash)  will  escape  the  character  it  pre¬ 
cedes. 

Each  arguments-list  is  constructed  starting  with  the  initial-arguments,  followed  by  some  number  of  argu¬ 
ments  read  from  the  standard  input  (Exception:  see  the  -i  option).  Options  -i,  -1,  and  -n  determine  how 
arguments  are  selected  for  each  command  invocation.  When  none  of  these  options  are  coded,  the  initial- 
arguments  are  followed  by  arguments  read  continuously  from  the  standard  input  until  an  internal  buffer  is 
full,  and  then  command  is  executed  with  the  accumulated  arguments.  This  process  is  repeated  until  there 
are  none  left.  When  there  are  option  conflicts  (for  instance,  -I  versus  -n),  the  last  option  takes  precedence. 

xargs  will  terminate  if  it  receives  a  return  code  of  ~1,  or  if  it  cannot  execute  command.  When  command  is 
a  shell  script,  it  should  explicitly  exit  (see  sh(l))  with  an  appropriate  value  to  avoid  accidentally  returning 
with  -1. 

OPTIONS 

“P  Prompt  mode.  The  user  is  asked  whether  to  execute  command  each  invocation.  Trace 

mode  (— t)  is  turned  on  to  print  the  command  instance  to  be  executed,  followed  by  a  ? . . . 
prompt.  A  reply  of  y  (optionally  followed  by  anything)  will  execute  the  command;  any¬ 
thing  else,  including  just  a  return,  skips  that  particular  invocation  of  command. 

Trace  mode.  The  command  and  each  constructed  argument  list  are  echoed  to  file 
descriptor  2  just  prior  to  their  execution. 

-X  Terminate  xargs  if  any  argument  list  would  be  greater  than  size  characters;  -x  is  forced 

by  the  options  -i  and  -1.  When  neither  of  the  options  -i,  -1,  or  — n  are  coded,  the  total 
length  of  all  arguments  must  be  within  the  size  limit. 

-eeofstr  eofstr  is  taken  as  the  logical  EOF  string.  (underbar)  is  assumed  for  the  logical  EOF 

string  if  -e  is  not  coded.  The  value  -e  with  no  eofstr  coded  turns  off  the  logical  EOF 
string  capability  (underbar  is  taken  literally),  xargs  reads  the  standard  input  until  either 
EOF  or  the  logical  EOF  string  is  encountered. 

-ireplstr  Insert  mode:  command  is  executed  for  each  line  from  the  standard  input,  taking  the  en¬ 

tire  line  as  a  single  argument,  inserting  it  in  initial-arguments  for  each  occurrence  of 
replstr.  A  maximum  of  5  arguments  in  initial-arguments  may  each  contain  one  or  more 


Sun  Release  4.1 


Last  change:  17  September  1989 


669 


XARGS(IV) 


USER  COMMANDS 


XARGS(IV) 


instances  of  replstr.  SPACE  and  TAB  characters  at  the  beginning  of  each  line  are  thrown 
away.  Constructed  arguments  may  not  grow  larger  than  255  characters,  and  option  -x  is 
also  forced.  {  }  is  assumed  for  replstr  if  not  specified. 

—{number  command  is  executed  for  each  nonempty  number  lines  of  arguments  from  the  standard 

input  The  last  invocation  of  command  will  be  with  fewer  lines  of  arguments  if  fewer 
than  number  remain.  A  line  is  considered  to  end  with  the  first  NEWUNE  unless  the  last 
character  of  the  line  is  a  SPACE  or  a  TAB;  a  trailing  SPACE  or  TAB  signals  continuation 
through  the  next  non-empty  line.  If  number  is  omitted,  1  is  assumed.  The  -x  option  is 
forced. 

-nnumber  Execute  command  using  as  many  standard  input  arguments  as  possible,  up  to  number  ar¬ 

guments  maximum.  Fewer  arguments  will  be  used  if  their  total  size  is  greater  than  size 
characters,  and  for  the  last  invocation  if  there  are  fewer  than  number  arguments  remain¬ 
ing.  If  option  -X  is  also  coded,  each  number  arguments  must  fit  in  the  size  limitation, 
else  xargs  terminates  execution. 

-ssize  The  maximum  total  size  of  each  argument  list  is  set  to  size  characters;  size  must  be  a  po¬ 

sitive  integer  less  than  or  equal  to  470.  If  -s  is  not  coded,  470  is  taken  as  the  default. 
Note:  the  character  count  for  size  includes  one  extra  character  for  each  argument  and  the 
count  of  characters  in  the  command  name. 

EXAMPLES 

The  following  will  move  all  files  from  directory  $1  to  directory  $2,  and  echo  each  move  command  just  be¬ 
fore  doing  it: 

Is  $1  I  xargs  -i  -t  mv  $l/{ }  $2/{ } 

The  following  will  combine  the  output  of  the  parenthesized  commands  onto  one  line,  which  is  then  echoed 

to  the  end  of  file  log: 

(logname;  date;  echo  $0  |  xargs  »log 

The  user  is  asked  which  files  in  the  cujrent  directory  are  to  be  archived  and  archives  them  into  arch(l)  one 

at  a  time,  or  many  at  a  time. 

Is  I  xargs  ~p  -I  ar  r  arch 

Is  I  xargs  “p  -1  I  xargs  ar  r  arch 

The  following  will  execute  difT(l)  with  successive  pairs  of  arguments  originally  typed  as  shell  arguments: 

echo  $♦  I  xargs  ~n2  diff 

SEE  ALSO 

arch(l),diff(l),  sh(l) 
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NAME 

xsend,  xget,  enroll  -  send  or  receive  secret  mail 

SYNOPSIS 

xsend  username 

xget 

enroll 

DESCRIPTION 

These  commands  implement  a  secure  communication  channel,  which  is  like  mail(l),  but  no  one  can  read 
the  messages  except  the  intended  recipient.  The  method  embodies  a  public-key  cryptosystem  using  knap¬ 
sacks. 

To  receive  messages,  use  enroll;  it  asks  you  for  a  password  that  you  must  subsequently  quote  in  order  to 
receive  secret  mail. 

To  receive  secret  mail,  use  xget.  It  asks  for  your  password,  then  gives  you  the  messages. 

To  send  secret  mail,  use  xsend  in  the  same  manner  as  the  ordinary  mail  command.  Unlike  mail,  xsend  ac¬ 
cepts  only  one  target.  A  message  announcing  the  receipt  of  secret  mail  is  also  sent  by  ordinary  mail. 

FILES 

/var/spool/secretmail/*.key  keys 
/var/spooI/secretmail/+.[0-9]  messages 

SEE  ALSO 

mail(l) 

BUGS 

The  knapsack  public-key  cryptosystem  is  known  to  be  breakable. 

Secret  mail  should  be  integrated  with  ordinary  mail. 

The  announcement  of  secret  mail  makes  “traffic  analysis”  possible. 
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NAME 

xstr  -  extract  strings  from  C  programs  to  implement  shared  strings 
SYNOPSIS 

xstr  -c  filename  [  -v  ]  [  ~1  array  ] 

xstr  [  -1  array  ] 

xstr  filename  [  -v  ]  [  -I  array  ] 

DESCRIPTION 

xstr  maintains  a  file  called  strings  into  which  strings  in  component  parts  of  a  large  program  are  hashed. 
These  strings  are  replaced  with  references  to  this  common  area.  This  serves  to  implement  shared  constant 
strings,  which  are  most  useful  if  they  are  also  read-only. 

The  command 

xstr  -c  filename 

extracts  the  strings  from  the  C  source  in  name,  replacing  string  references  by  expressions  of  the  form 
&xstr[number]  for  some  number.  An  appropriate  declaration  of  xstr  is  prepended  to  the  file.  The  result¬ 
ing  C  text  is  placed  in  the  file  x.c,  to  then  be  compiled.  The  strings  from  this  file  are  placed  in  the  strings 
data  base  if  they  are  not  there  already.  Repeated  strings  and  strings  which  are  suffixes  of  existing  strings 
do  not  cause  changes  to  the  data  base. 

After  all  components  of  a  large  program  have  been  compiled,  a  file  declaring  the  common  xstr  space  called 
XS.C  can  be  created  by  a  command  of  the  form 

xstr 

This  XS.C  file  should  then  be  compiled  and  loaded  with  the  rest  of  the  program.  If  possible,  the  array  can  be 
made  read-only  (shared)  saving  space  and  swap  overhead. 

xstr  can  also  be  used  on  a  single  file.  A  command 

xstr  filename 

creates  files  x.c  and  xs.c  as  before,  without  using  or  affecting  any  strings  file  in  the  same  directory. 

It  may  be  useful  to  run  xstr  after  the  C  preprocessor  if  any  macro  definitions  yield  strings  or  if  there  is  con¬ 
ditional  code  which  contains  strings  which  may  not,  in  fact,  be  needed,  xstr  reads  from  the  standard  input 
when  the  argument  is  given.  An  appropriate  command  sequence  for  running  xstr  after  the  C  prepro¬ 
cessor  is: 

cc  ~E  name.c  |  xstr  -c  - 

CC  -C  X.C 

mv  x.o  name.o 

xstr  does  not  touch  the  file  strings  unless  new  items  are  added;  thus  niake(l)  can  avoid  remaking  xs.o  un¬ 
less  truly  necessary. 

OPTIONS 

-c  filename  Take  C  source  text  from  filename . 

-V  Verbose:  display  a  progress  report  indicating  where  new  or  duplicate  strings  were  found. 

-1  array  Specify  the  named  array  in  program  references  to  abstracted  strings.  The  default  array 
name  is  xstr. 
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FILES 


strings 

x.c 


XS.C 

/tmp/xs* 


SEE  ALSO 

inake(l),  mkstr(l) 


data  base  of  strings 

massaged  C  source 

C  source  for  definition  of  array  “xstr” 

temp  file  when  xstr  filename  doesn’t  touch  strings 


BUGS 

If  a  string  is  a  suffix  of  another  string  in  the  data  base,  but  the  shorter  string  is  seen  first  by  xstr  both  strings 
will  be  placed  in  the  data  base,  when  just  placing  the  longer  one  there  would  do. 
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NAME 

yacc  “  yet  another  compiler-compiler:  parsing  program  generator 
SYNOPSIS 

yacc  [  -dvlt  ]  grammar 
DESCRIPTION 

yacc  converts  a  context-free  grammar  into  a  set  of  tables  for  a  simple  automaton  which  executes  an  LR(1) 
parsing  algorithm.  The  grammar  may  be  ambiguous,  in  which  case  specified  precedence  rules  may  be  used 
to  break  those  ambiguities. 

The  output  file,  y.tab.c,  must  be  compiled  by  the  C  compiler  to  produce  a  function  named  yyparse().  The 
yyparseO  function  must  be  loaded  with  the  lexical  analyzer  yylex(),  as  well  as  mainO  and  the  error  han¬ 
dling  routine  yyerror().  These  routines  must  be  supplied  by  the  user;  lex(l)  is  useful  for  creating  lexical 
analyzers  usable  by  yacc-produced  parsers. 

OPTIONS 

-d  Generate  the  file  y.tab.h  with  the  define  statements  that  associate  the  yacc-assigned  “token 
codes”  with  the  user-declared  “token  names”  so  that  source  files  other  than  y.tab.c  can  access  the 
token  codes. 

“V  Prepare  the  file  y.output  containing  a  description  of  the  parsing  tables  and  a  report  on  conflicts 
generated  by  ambiguities  in  the  grammar. 

-I  Generate  y.tab.c  containing  no  numbered  line  directives. 

-t  Set  the  preprocessor  symbol  yydebug,  so  y.tab.c  will  be  compiled  with  runtime  debugging  code. 

FILES 

y.output  description  of  parsing  tables  and  conflict  report 

y.tab.c  output  parser 

y.tab.h  defines  for  token  names 

yacc.tmp^  yacc.acts  temporary  files 
/ usr/lib/yaccpar  parser  prototype  for  C  programs 

/usr/5Iib/liby.a  library  provides  primitive  routines  mainO  and  yyerror()  to  facilitate  the  initial 

use  of  yacc. 

SEE  ALSO 

cc(lV),  lex(l) 

Programming  Utilities  and  Libraries 

LR  Parsing  by  A.  V.  Aho  and  S.  C.  Johnson,  Computing  Surveys,  June,  1974 
DIAGNOSTICS 

The  number  of  reduce-reduce  and  shift-reduce  conflicts  is  reported  on  the  standard  output;  a  more  detailed 
report  is  found  in  the  y.output  file.  Similarly,  it  is  also  reported  if  some  rules  are  not  reachable  from  the 
start  symbol. 

NOTES 

Because  the  cc(lV)  command  does  not  generate  or  support  8-bit  symbol  names,  it  is  inappropriate  to  make 
yacc  8-bit  clean.  See  cc(lV)  for  an  explanation  about  why  cc  is  not  8-bit  clean. 

BUGS 

Because  file  names  are  fixed,  no  more  than  one  yacc  process  should  be  active  in  a  given  directory  at  a  time. 
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NAME 

yes  -  be  repetitively  affirmative 

SYNOPSIS 

yes  [  expletive  ] 

DESCRIPTION 

yes  repeatedly  outputs  y,  or  if  expletive  is  given,  that  is  output  repeatedly.  Termination  is  by  typing  an  in¬ 
terrupt  character. 
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NAME 

ypcat  -  print  values  in  a  NIS  data  base 
SYNOPSIS 

ypcat  [  -kt  ]  [  -d  domainname  ]  mname 
ypcat  -X 
AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4.1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

ypcat  prints  out  values  in  a  Network  Information  Service  (NIS)  map  specified  by  mname,  which  may  be  ei¬ 
ther  a  map  name  or  a  map  nickname  .  Since  ypcat  uses  the  NIS  service,  no  NIS  server  is  specified. 

To  look  at  the  network-wide  password  database,  passwd.byname,  (with  the  nickname  passwd).  type  in: 
ypcat  passwd 

Refer  to  ypfiiles(5)  and  ypserv(8)  for  an  overview  of  the  NIS  service. 

OPTIONS 

-k  Display  the  keys  for  those  maps  in  which  the  values  are  null  or  the  key  is  not  part  of  the  value. 

-t  Inhibit  translation  of  mname  to  map  name.  For  example,  'ypcat  -t  passwd’  will  fail  because 

there  is  no  map  named  passwd,  whereas  ‘  ypcat  passwd  ’  will  be  translated  to  ‘ypcat 
passwd.byname\ 

-d  domainname 

Specify  a  domain  other  than  the  default  domain.  The  default  domain  is  returned  by  domainname. 

“X  Display  the  map  nickname  table.  This  lists  the  nicknames  (mname  s)  the  command  knows  of,  and 
indicates  the  mapname  associated  with  each  nickname. 

SEE  ALSO 

domainname(l),  ypmatch(l),  ypfiles(5),  ypserv(8) 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed.  The  name  Yellow  Pages  is  a  registered  trade¬ 
mark  in  the  United  Kingdom  of  British  Telecommunications  pic,  and  may  not  be  used  without  permission. 
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NAME 

ypmatch  ~  print  the  value  of  one  or  more  keys  from  a  NIS  map 
SYNOPSIS 

ypmatch  [  “d  domain  ]  [  ~k  ]  [  -t  ]  . . .  mname 

ypmatch  -x 
AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4J 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

ypmatch  prints  the  values  associated  with  one  or  more  keys  from  the  Network  Information  Service  (NIS) 
map  specified  by  mname,  which  may  be  either  a  mapname  or  an  map  nickname. 

Multiple  keys  can  be  specified;  the  same  map  will  be  searched  for  all  .  The  keys  must  be  exact  values 
insofar  as  capitalization  and  length  are  concerned.  No  pattern  matching  is  available.  If  a  key  is  not 
matched,  a  diagnostic  message  is  produced. 

OPTIONS 

-d  Specify  a  domain  other  than  the  default  domain. 

-k  Before  printing  the  value  of  a  key,  print  the  key  itself,  followed  by  a  colon  .  This  is  useful  only 
if  the  keys  are  not  duplicated  in  the  values,  or  you’ve  specified  so  many  keys  that  the  output  could 
be  confusing. 

-t  Inhibit  translation  of  nickname  to  mapname.  For  example,  ‘ypmatch  -t  zippy  passwd  ’  will  fail 
because  there  is  no  map  named  passwd,  while  ‘ypmatch  zippy  passwd  ’  will  be  translated  to 
‘ypmatch  zippy  passwd.byname  ’. 

“X  Display  the  map  nickname  table.  This  lists  the  nicknames  {mnames)  the  command  knows  of,  and 
indicates  the  mapname  associated  with  each  nickname. 

SEE  ALSO 

ypcat(l),  ypfiles(5) 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed.  The  name  Yellow  Pages  is  a  registered  trade¬ 
mark  in  the  United  Kingdom  of  British  Telecommunications  pic,  and  may  not  be  used  without  permission. 
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NAME 

yppasswd  -  change  your  network  password  in  the  NIS  database 
SYNOPSIS 

yppasswd  [  username  ] 
ypchfn  [  username  ] 
ypchsh  [  username  ] 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4,1 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

yppasswd  changes  (or  installs)  the  network  password  associated  with  the  user  username  (your  own  name 
by  default)  in  the  Network  Information  Service  (NIS)  database.  The  NIS  password  may  be  different  from 
the  local  one  on  your  own  machine.  See  passwd(l). 

ypchfn  changes  the  full  name  associated  with  username  in  the  NIS  database. 

ypchsh  changes  the  login  shell  associated  with  username  in  the  NIS  database. 

yppasswd  prompts  for  the  old  NIS  password,  and  then  for  the  new  one.  You  must  type  in  the  old  password 
correctly  for  the  change  to  take  effect.  The  new  password  must  be  typed  twice,  to  forestall  mistakes. 

New  passwords  must  be  at  least  four  characters  long,  if  they  use  a  sufficiently  rich  alphabet,  and  at  least  six 
characters  long  if  monocase.  These  rules  are  relaxed  if  you  are  insistent  enough.  Only  the  owner  of  the 
name  or  the  super-user  may  change  a  password;  in  either  case  you  must  prove  you  know  the  old  password. 

The  NIS  password  daemon,  yppasswdd(8C)  must  be  running  on  your  NIS  server  in  order  for  the  new  pass¬ 
word  to  take  effect. 

SEE  ALSO 

passwd(l),  ypfiles(5),  yppasswdd(8C) 

BUGS 

The  update  protocol  passes  all  the  information  to  the  server  in  one  RPC  call,  without  ever  looking  at  it. 
Thus  if  you  type  in  your  old  password  incorrectly,  you  will  not  be  notified  until  after  you  have  entered  your 
new  password. 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed.  The  name  Yellow  Pages  is  a  registered  trade¬ 
mark  in  the  United  Kingdom  of  British  Telecommunications  pic,  and  may  not  be  used  without  permission. 
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NAME 

ypwhich  -  return  hostname  of  NIS  server  or  map  master 
SYNOPSIS 

ypwhich  [  -d  [  domain  ]  ]  [  -VI !  -V2  ]  [  hostname  J 
ypwhich  [  -t  mapname  ]  [  -d  domain  ]  -m  [  mname  ] 
ypwhich  -x 

AVAILABILITY 

This  command  is  available  with  the  Networking  software  installation  option.  Refer  to  Installing  SunOS  4J 
for  information  on  how  to  install  optional  software. 

DESCRIPTION 

ypwhich  tells  which  Network  Information  Service  (NIS)  server  supplies  NIS  services  to  an  NIS  client,  or 
which  is  the  master  for  a  map.  If  invoked  without  arguments,  it  gives  the  NIS  server  for  the  local  machine. 
If  hostname  is  specified,  that  machine  is  queried  to  find  out  which  NIS  server  it  is  using. 

Refer  to  ypfiles(5)  and  ypserv(8)  for  an  overview  of  the  NIS  services. 

OPTIONS 

“d  Use  domain  instead  of  the  default  domain. 

-VI  Which  server  is  serving  v.l  NIS  protocol-speaking  client  processes. 

-V2  Which  server  is  serving  v.2  NIS  protocol  client  processes. 

If  neither  version  is  specified,  ypwhich  attempts  to  locate  the  server  that  supplies  the  (current)  v.2 
services.  If  there  is  no  v.2  server  currently  bound,  ypwhich  then  attempts  to  locate  the  server  sup¬ 
plying  the  v.l  services.  Since  NIS  servers  and  NIS  clients  are  both  backward  compatible,  the  user 
need  seldom  be  concerned  about  which  version  is  currently  in  use. 

-t  mapname 

Inhibit  nickname  translation;  useful  if  there  is  a  mapname  identical  to  a  nickname.  This  is  not  true 
of  any  Sun-supplied  map. 

-m  Find  the  master  NIS  server  for  a  map.  No  hostname  can  be  specified  with  the  -m  option,  mname 
can  be  a  mapname,  or  a  nickname  for  a  map.  When  mname  is  omitted,  produce  a  list  available 
maps. 

-X  Display  the  map  nickname  table.  This  lists  the  nicknames  (mnames)  the  command  knows  of,  and 
indicates  the  mapname  associated  with  each  nickname. 

SEE  ALSO 

ypfiles(5),  rpcinfo(8C),  ypserv(8),  ypset(8) 

NOTES 

The  Network  Information  Service  (NIS)  was  formerly  known  as  Sun  Yellow  Pages  (YP).  The  functionality 
of  the  two  remains  the  same;  only  the  name  has  changed.  The  name  Yellow  Pages  is  a  registered  trade¬ 
mark  in  the  United  Kingdom  of  British  Telecommunications  pic,  and  may  not  be  used  without  permission. 
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